bggg-creator-image2psd

BGGG Creator Image2PSD

Use this skill to organize image assets into editable PSD raster layers. The core script is scripts/image2psd.py. It does not depend on Photoshop or ImageMagick and can independently write a PSD with layer names, alpha channels, and a composite preview.

Codex adaptation default strategy

When handling image-to-PSD in Codex, by default work with the capabilities of the imagegen skill:

• First use Codex's visual understanding capability to determine the layer structure, the boundaries of subject/background/text/decoration, and which areas need background reconstruction.
• If the user requests generating from a description, filling in missing elements, removing objects and then filling in the background, or extracting cleaner standalone product/subject images, prioritize using the imagegen skill's built-in image generation/editing capabilities to generate assets within the project, then hand them to this skill to assemble the PSD.
• If the user explicitly requests "do not change relative positions" or "assemble directly in Photoshop", prioritize preserving the original image pixels: output each layer as a same-size full-canvas transparent PNG, changing only alpha without redrawing content. Only background erasure/hole filling may use inpaint or imagegen assistance.
• Do not leave imagegen's default output in $CODEX_HOME. Images to be used by the project must be copied into this skill's project directory.

Project directory conventions

Create a separate project directory for each image processing task, placed under this skill's folder:

bggg-creator-image2psd/
└── projects/
    └── YYYYMMDD_slug/
        ├── original_reference.png
        ├── manifest.json
        ├── layer_sources/
        ├── psd_full_canvas_layers/
        ├── output.psd
        ├── output.preview.png
        ├── psd_full_canvas_layers.zip
        └── process_notes.md

Naming rules:

• YYYYMMDD_slug Use the current date and a short English/pinyin task name, for example 20260503_lifestyle_product.
• original_reference.png is the copy of the source image for this processing task.
• layer_sources/ Saves the transparent layer sources used for assembly.
• psd_full_canvas_layers/ Saves full-canvas PNG layers that Photoshop can stack directly in their original positions.
• process_notes.md Records the layer division, whether imagegen was used, validation results, and known limitations.

Workflow

1. Determine the task type:

   • Multiple element images already exist: copy them to the project directory, use assemble, and write the manifest in layer order.
   • There is only one flat image and relative positions must be preserved: perform semantic/region layer splitting, keeping each layer the same size as the original image; use inpaint or imagegen assistance to clean up the areas split out from the background layer.
   • There is only one flat image and only rough splitting is needed: use split-colors to split layers by color clustering, and explain that it is not semantic object layer splitting.
   • The user wants to generate a PSD from a description: first use Codex imagegen to separately generate project assets such as background, subject, and text/decoration, then use assemble to composite the PSD.

2. Create projects/YYYYMMDD_slug/, and put the source image and all outputs into it. By default, initialize with the script:

   python3 bggg-creator-image2psd/scripts/init_project.py lifestyle_product \
     --source 用户附件.png \
     --date 20260503
   

   If imagegen was used, first copy the generated results under $CODEX_HOME to that project's imagegen_assets/, then proceed to the layer splitting or compositing workflow.

3. Determine the canvas size. Prefer the source image size; poster-type tasks require explicit width and height.

4. Handle transparency:

   • Use remove_background: none。
   • for the background layer. Logos, text, and decorative images commonly use remove_background: white。
   • For elements that are easily swallowed by a white background, such as white sails, white products, and light-colored subjects, use remove_background: white-preserve。
   • For non-white solid backgrounds, use corner or color。

5. Run the script to output a PSD, a preview PNG, and an optional per-layer PNG directory/zip.

6. Verify the output: check the layer_count, preview PNG, and PSD file size in the script's JSON summary; use Pillow or Photoshop/Photopea to check PSD readability.

7. Write process_notes.md, recording layers, paths, verification, and limitations.

Common Commands

Compose from a manifest:

python3 bggg-creator-image2psd/scripts/image2psd.py assemble \
  --manifest work/manifest.json \
  --output work/output.psd \
  --preview work/output.preview.png \
  --save-layers work/layers \
  --zip-layers work/layers.zip

Compose multiple images directly, with the first image as the background:

python3 bggg-creator-image2psd/scripts/image2psd.py assemble bg.png title.png logo.png \
  --first-is-background \
  --names "Background,Title,Logo" \
  --output output.psd \
  --save-layers layers

Split a single flat image into PSD layers by color:

python3 bggg-creator-image2psd/scripts/image2psd.py split-colors poster.png \
  --output poster-color-layers.psd \
  --num-colors 10 \
  --ignore-color white \
  --save-layers poster-color-layers

Manifest Format

Use a manifest to manage complex PSDs. The layer array is ordered from bottom to top.

{
  "canvas": {
    "width": 1122,
    "height": 1402,
    "composite_background": "#ffffff"
  },
  "output": "poster.psd",
  "preview": "poster.preview.png",
  "save_layers_dir": "layers",
  "layers": [
    {
      "name": "Background",
      "file": "assets/background.png",
      "fit": "cover",
      "remove_background": "none"
    },
    {
      "name": "Ship and Waves",
      "file": "assets/ship.png",
      "remove_background": "white-preserve"
    },
    {
      "name": "Title",
      "type": "text",
      "text": "AI Commerce Summit",
      "x": 80,
      "y": 120,
      "font_size": 72,
      "color": "#41270d",
      "max_width": 900
    }
  ]
}

Key layer fields:

• file/path/src: image path; relative paths in the manifest are resolved from the manifest's directory.
• type: "text": rendered with PIL as an independent raster text layer, not a Photoshop editable text object.
• x, y: top-left offset of the image or text layer.
• fit: none、contain、cover、stretch。
• remove_background: none、white、white-preserve、corner、color。
• opacity: 0 to 1.

Image Generation to PSD

In Codex, treat imagegen as a reinforcement tool by default, not the only approach. Break the design into independent elements to generate or edit, rather than generating just one complete poster:

• Background: full canvas, usually without background removal.
• Subject/product/person/boat/prop: white or transparent background; use white or white-preserve to remove the background when compositing.
• Logo, title, schedule, decoration: generate separately where possible or rebuild using the manifest's text layer.
• Each element's prompt should include constraints such as canvas size, viewing angle, clean edges, and no shadows contaminating the background.

If image generation yields only one complete image, first use split-colors to do the minimum-viability layer split for editability, then generate the key elements as needed per the user's requirements.

Lessons from Semantic Layer Splitting of a Single Image

After reviewing successful cases, prefer this order for converting a single image to PSD:

1. Copy the source image to the project directory, keeping the original dimensions.
2. First list the layers, grouped by "background/subject/decoration/text/shadow or light effect".
3. For each movable object, output a full-canvas transparent PNG with no cropping of position, so it can be stacked directly in Photoshop.
4. For the background layer, use the union mask of the split-out layers for inpainting; if necessary, expand the mask a second time to clean up residual traces.
5. Compare the preview image with the original by pixel difference or visual inspection; when text/subject edges are found to be cropped, prefer expanding the mask box rather than moving the layer.
6. If the source image has no local file, first ask the user for the source file path; do not use imagegen to redraw and pass it off as the original layer split.

When to Read the References

• Before modifying core scripts, read references/implementation-notes.md。
• When you need to trace inspiration from external projects, read references/source-projects.md。
• Do not use reference/ external repositories cloned under it as runtime dependencies; they are only development references.

Output Requirements

On delivery, at least state:

• PSD path.
• Preview PNG path.
• Number of layers and main layer names.
• Whether per-layer PNG/zip was generated.
• Project directory path.
• If you have not verified the Photoshop opening result, explicitly say that verification is limited to the script and preview.