ecommerce-material-studio

E-commerce Material Studio / E-commerce Material Studio

A one-stop toolchain for generating e-commerce product assets (main images/detail images/scene images). Input product images → automatically complete category recognition, style matching, scene compositing, text overlay, quality inspection, multi-platform adaptation, and batch delivery.

One-stop pipeline for e-commerce product images: category detection → style matching → scene compositing → text overlay → quality check → platform adaptation → batch delivery.

When to use / When to use

The user needs to generatee-commerce main images/detail images(e.g., "help me make a set of main images for a shaver")
Needsproduct image compositing into scenes(white background image → scene image)
Needsbrand overlay(Logo/guarantee bar/selling point text/badge)
Needsmulti-platform size adaptation(7 platforms including Taobao/Kuaishou/Douyin/Pinduoduo/JD.com, etc.)
Needsbatch generationof multiple product assets

Workflow / Workflow

# 0. 环境依赖（一次性）
pip install Pillow numpy scipy

1. Category recognition: input product image → recognize category/style

python3 scripts/category_detector.py --image product.png

2. Style matching: category + price range + platform + brand → recommend template

python3 scripts/style_matcher.py --category personal care appliances --sub-category shaver --price 169 --platform kuaishou

3. Scene-aware compositing (core): library call (SceneAwareCompositor is a Python library, not a CLI)

python3 -c " from PIL import Image from scripts.scene_aware_compositor import SceneAwareCompositor c = SceneAwareCompositor() scene = Image.open('scene.jpg'); product = Image.open('product.png') result = c.composite(scene_image=scene, product_image=product, scene_type='lifestyle_bathroom', position=(0.5, 0.45)) result.save('result.png') "

4. Unified text overlay (process all text layers in plan.json)

python3 scripts/text_engine.py --plan output/plan.json --brand langke --scene-tone dark

5. Automatic quality inspection (read plan.json + check the finished image)

python3 scripts/quality_check.py --plan output/plan.json

6. Multi-platform size adaptation

python3 scripts/platform_adapter.py --input-dir ./output --platforms kuaishou --output-dir ./platform_output

7. Standardized delivery packaging (automatically generate usage guide + checklist + zip)

python3 scripts/delivery_packager.py --project-dir ./output --product-name "Sample Product"

8. Batch processing (multiple products, resumable transfer)

python3 scripts/batch_processor.py --input products.json --output-dir ./batch --prepare


## 模块清单 / Modules

| 模块 | 功能 | 依赖 |
|:---|:---|:---|
| `category_detector.py` | 品类识别（色调/材质→子品类） | Pillow |
| `style_matcher.py` | 风格匹配（品类+价位+平台+品牌→模板） | 无 |
| `brand_loader.py` | 品牌配置加载（多品牌/Logo选择） | 无 |
| `text_engine.py` | 统一文字引擎（z-index/避让/对比度） | Pillow |
| `quality_check.py` | 自动质检（分辨率/可读性/Logo/完整/重叠） | Pillow |
| `preference_memory.py` | 偏好记忆（跨项目复用风格） | 无 |
| `batch_processor.py` | 批量处理（断点续传/重试/报告） | 无 |
| `platform_adapter.py` | 7 平台尺寸适配（resize/crop/压缩） | Pillow |
| `delivery_packager.py` | 交付打包（使用指南+清单+zip） | Pillow |
| `layout_engine.py` | 布局引擎（物理尺寸→像素比例） | 无 |
| `scene_aware_compositor.py` | 场景感知合成（参照物尺度/透视/景深） | Pillow+numpy+scipy |

## 数据文件 / Data (references/)

- `category_templates.json` — 12 品类场景模板库（推荐场景/prompt/配色/文字风格）
- `product_profiles.json` — 产品档案库（示例：example_shaver）
- `brand_profiles/langke.json` — 示例品牌配置（朗科=示例品牌，非真实）
- `brand_config_template.json` — 新建品牌模板
- `user_preferences.json` — 偏好记忆库（模板）

## 注意事项 / Notes

- **字体**：`text_engine.py` 需要中文字体（macOS: `/System/Library/Fonts/PingFang.ttc`，Linux: NotoSansCJK，Windows: msyh.ttc）——按需修改 `FONT_PATHS_BOLD`/`FONT_PATHS_REGULAR` 常量
- **品牌配置**：用 `brand_config_template.json` 新建自己的品牌（含 Logo 路径/色系/保障条）
- **合成模式**：`scene_aware_compositor.py` 支持场景感知模式（自动算尺度）和兼容模式（固定 scale）
- 参考数据中的"朗科/LangKe"为**示例品牌**，可直接替换为自己的品牌配置

About this skill

When to use / When to use

Workflow / Workflow