ssjsjdjj/visual-detail-image-processor

Visual Detail Page Template Generation

Default Delivery: Editable Long Image per Product Variant

• Detail page template generation uses the Editable Long Image PSD Rules by default. For each product variant within the input scope, an independent long image with the replaced content for that specific variant will be output and archived per variant.
• The current default layout uses 小山行风感洞洞裤-终.psb (790 × 40000 px), delivering PSB with the full canvas preserved. An old master can be explicitly specified in the task. Item numbers, materials, size ranges, and tables follow the original per-character font rules.
• Product images and model/scene images use separately replaceable embedded smart objects. Product copy, color names, and table cells use native Photoshop text layers. For new masters, S3 Size Selection, S4 Quick Size Select, and S5 Fit Report adjust the grid according to the actual number of rows and columns, preserving the master's section titles, colors, module positions, and fixed design.
• When the user explicitly requests JPG modules, use the JPG workflow below. When the user requests JPGs simultaneously, export as an additional attachment.

Template Generation per Product Variant

1. Inventory all product variants within the input root directory, cross-reference with the PSD/PSB master and actual layers. Distinguish between fixed design elements and content that varies per variant.
2. For each variant, prepare a task JSON and a unique output path. Bind product copy, size chart, quick size select, existing fit reports, product images, model/scene images, and other modules that change per variant. Existing product JSON can be reused as a data source.
3. Use scripts/build_editable_long_psd.py to generate JSX per variant, then execute through Photoshop. If master slots cannot be matched or materials for that variant are missing, list the item number, the module, and the missing items. Legacy dynamic content, merged JPGs, or incomplete master copies must not be delivered as the final product for that variant.
4. Reopen each output PSD, verify the item number, visible content, and editability of text and tables. Check that product images and scene images can open their smart object content independently without relying on external links. List the output path for each variant and any incomplete items.

Environment Setup

Before first use, initialize the Python environment in the skill's scripts/ directory:

cd scripts
uv sync

If uv is not installed, run:

• macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
• Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After initialization is complete, always use the Python virtual environment from .venv to execute tool scripts.

Input Structure

The product material folder structure is typically:

<input-root>/
  <product-folder>/
    product_data.json
    产品信息.jpg|png
    选尺码.png|jpg|jpeg
    尺码快选.png|jpg|jpeg
    透明图/
      <color-name>.png
    模特图/
      1.jpg
      2.jpg
      3.jpg

The built-in template directory is:

template/

The template structure is typically:

template/
  01产品信息.jpg
  02透明图.jpg
  03选尺码.jpg
  04推荐尺码.jpg
  05尺码快选.jpg
  模特图1.jpg
  模特图2.jpg
  模特图2覆盖.png
  模特图3.jpg

Execution Flow

1. First, confirm the input root and output root directories; by default, use the skill's built-in template/ and assets/ directories.
2. If the product does not yet have structured data, first use GPT's image recognition capability to read the 产品信息, 选尺码, and 尺码快选 images. Generate a JSON by merging the data across these images and save it to scripts/output/product_data/<product-folder-name>-product_data-<timestamp>.json.
3. Read the Image Table to Data Rules, validate the product JSON, write uncertain content into warnings, and do not fabricate data.
4. Before running the rendering script, first scan whether the product has model image materials. As long as readable model images exist, you must use AI aesthetic selection for image/crop selection. For each available model image, output the original image pixel coordinates and save them to scripts/output/visual_model_selection/visual_model_selection-<timestamp>.json.
5. Run the generic batch processing script. Do not hardcode product names or product data. If an AI coordinate JSON was generated in this run, it must be explicitly passed with --visual-model-selection "<coordinate-json-path>". Do not rely on the script to automatically fall back or wait for data.
6. Generate an output subfolder for each product, preserving the original product folder name.
7. Output final images only to --output-root/<product-folder>/. Output the batch processing report uniformly to scripts/output/report/render_report-<timestamp>.json.
8. If the user requests "layered files", "PSD", "Photoshop quick rework", or designer-ready delivery, use scripts/create_layered_psd_package.py instead. It will synchronously generate JPGs, a PSD manifest, and a Photoshop JSX assembly script.
9. After output, perform a visual and size check, especially checking for white frames, green line residue, table artifacts, text misalignment, transparency image size jumps, and model image cropping.
10. Read the report to confirm that all model images with coordinates have mode set to visual_model_selection. If cover_crop is used as a fallback, explain each case by stating whether the coordinate was missing, invalid, the source file was missing, or the current environment could not reliably make a visual judgment.

Photoshop Layered File Workflow

When the user needs files that a designer can adjust for rework, use the Photoshop layered workflow:

cd scripts
uv run python create_layered_psd_package.py `
  --input-root "<input-root>" `
  --output-root "<output-root>"

The script will generate the following in <output-root>/_photoshop_layered/:

layered_psd_manifest.json
build_layered_psd.jsx

Then, call Photoshop to generate the PSDs:

powershell -ExecutionPolicy Bypass -File run_photoshop_jsx.ps1 `
  -JsxPath "<output-root>/_photoshop_layered/build_layered_psd.jsx"

PSD output is placed in:

<output-root>/<product-folder>/_psd/

Layering conventions:

• The template background is isolated as a separate layer named 00 Background Template.
• Dynamic replacement content is separated into toggleable layers, such as product transparent images, model photos, table layers, and data area backgrounds.
• Each PSD includes a hidden 99 Final Reference (Hidden) layer by default for the designer to cross-check.
• Tables and complex mixed text are retained as pixel layers to ensure visual consistency; product information and color names are generated as Photoshop text layers where possible for easy rework.
• If you only want to rebuild PSDs from existing JPGs/materials without re-rendering JPGs, add the --skip-jpg-render flag.

Mandatory Reference Reading

Read the corresponding reference based on the task:

• Before processing any batch task, read Batch Execution Rules.
• When you need to understand built-in font resources, read Built-in Resource Rules.
• When you need to understand or replace template resources, read Built-in Template Resource Rules.
• When you need to extract data from image/table materials, read Image Table to Data Rules.
• When drawing text or encountering font issues, read Font and Text Rules.
• When processing 01产品信息.jpg, read Product Information Rules.
• When processing 02透明图.jpg, read Transparent Image Rules.
• When processing 03选尺码.jpg or 05尺码快选.jpg, read Table Rules.
• When processing 模特图1.jpg, 模特图2.jpg, 模特图3.jpg, read Model Image Rules.
• When you need to use AI subjective aesthetic cropping coordinates, read Smart Model Image Selection Rules.
• When using or maintaining scripts, read Script Instructions.
• When you need to output PSD layered files or control Photoshop, read Photoshop Layered File Rules.

Current Scripts

scripts/detail_template_replacer_2000.py
scripts/main.py
scripts/create_layered_psd_package.py
scripts/run_photoshop_jsx.ps1
scripts/create_product_data_template.py
scripts/validate_product_data.py

Running

Example command:

cd scripts
uv run python main.py `
  --input-root "<input-root>" `
  --output-root "<output-root>"

If model image materials exist for this run, first generate visual_model_selection-<timestamp>.json, then explicitly pass the coordinate file:

cd scripts
uv run python main.py `
  --input-root "<input-root>" `
  --output-root "<output-root>" `
  --visual-model-selection "output/visual_model_selection/visual_model_selection-<timestamp>.json"

If using an external data directory or external template directory:

cd scripts
uv run python main.py `
  --input-root "<input-root>" `
  --output-root "<output-root>" `
  --data-dir "<data-dir>" `
  --template-dir "<custom-template-dir>" `
  --visual-model-selection "<visual_model_selection-json>"

Acceptance Criteria

• Every input product folder must be processed or have a reason reported.
• All output images must have a width of 790px.
• Template fixed text, backgrounds, green blocks, logos, decorative lines, and overlays must not be destroyed by dynamic rendering.
• Product data must come from product_data.json or an equivalent structured file, and must not be hardcoded in Python.
• Empty values should be left blank; do not fill in defaults or infer values.
• There must be no white frames, green line residue, table artifacts, or white vertical lines on green table headers.
• Font sizes and weights for the same type of text must be consistent; mixed numbers must not jump up and down.
• Transparent images on the same page must be visually consistent in size; color names must be adjacent to the product and aligned with the same baseline.
• Model image subjects must not be deformed; priority should be given to ensuring the head and main body are intact.
• Batch processing sessions containing model image materials must first produce an AI coordinate JSON before running the script. The report must show visual_model_selection for the corresponding model images, unless a clear reason for the inability to use AI coordinates is given.