Image Mixer

Image Mixer

Interactive CLI tool for batch processing image overlays. Combines base product images with overlay badges/labels to create composite marketing images.

Overview

Image Mixer automates the process of adding overlay badges (like “Dual”, “Lite”, “Metal” rail indicators) to product images. Instead of manually editing each image, you can process multiple base × overlay combinations in one batch operation.

Key Features

• Interactive CLI with step-by-step prompts
• Batch processing for multiple base × overlay combinations
• Configurable positioning and sizing (percentage-based)
• Progress tracking with success/failure reporting
• Automatic directory handling with organized output

Installation

The tool is included in the main project. Install dependencies:

# From project root
pnpm install

# Or install only for image-mixer
cd sub-packages/image-mixer
pnpm install

Usage

Quick Start

# From project root
pnpm image-mixer

# Or from sub-package directory
cd sub-packages/image-mixer
pnpm start

Interactive Workflow

The CLI will guide you through the following steps:

1. Enter Base Image Slugs

Enter image slugs for base images (one per line, press Enter twice to finish):

zb40-red-a-4
zb40-red-a-5
zb40-red-b-2

2. Enter Overlay Image Slugs

Enter image slugs for overlay images (one per line, press Enter twice to finish):

overlay-rail-dual
overlay-rail-lite
overlay-rail-metal

3. Configure Overlay Settings

• Padding from edges: Distance from right/bottom edge (% of base image)

  • Default: 5%
  • Range: 0-50%
  • Same value applies to both right and bottom edges

• Overlay width: Width of overlay (% of base image width)

  • Default: 35%
  • Range: 1-100%
  • Height is calculated automatically (1
    aspect ratio)

4. Confirm and Process

Review the summary and confirm to start processing:

📋 Summary:
   Base images: 3
   Overlay images: 3
   Total combinations: 9
   Padding: 5%
   Overlay width: 35%

✓ Proceed with processing? (Y/n)

5. View Results

The tool processes all combinations and shows progress:

🔄 Processing images...

✓ [1/9] zb40-red-a-4--overlay-rail-dual.png
✓ [2/9] zb40-red-a-4--overlay-rail-lite.png
✓ [3/9] zb40-red-a-4--overlay-rail-metal.png
...

✓ Complete! 9 images saved to dist/

Image Processing Details

Source Images

• Location: /static/images/p/{slug}/mercari.png
• Format: PNG files (1600px width)
• Source: Generated by the Image Processor

Output Images

• Directory: sub-packages/image-mixer/dist/
• Format: PNG
• Naming: {base-slug}--{overlay-slug}.png
• Example: zb40-red-a-4--overlay-rail-dual.png

Overlay Positioning

Overlays are positioned in the bottom-right corner with:

• Aspect ratio: Always 1
  (square)
• Width: Configurable percentage of base image width
• Height: Equal to width (maintains 1
  ratio)
• Padding: Distance from right and bottom edges (same value for both)

Calculation Examples

For a 1600px × 1600px base image with default settings (5% padding, 35% width):

• Overlay dimensions: 560px × 560px (35% of 1600px)
• Padding: 80px (5% of 1600px)
• Position: 960px from left, 960px from top
• Right edge: 80px from right edge
• Bottom edge: 80px from bottom edge

Configuration Reference

Padding

Controls distance from right and bottom edges.

Overlay Width

Controls size of overlay relative to base image.

Error Handling

Common Errors

Missing base image:

✗ Base image not found: /static/images/p/invalid-slug/mercari.png

Solution: Verify the slug is correct and the image exists in /static/images/p/

Missing overlay image:

✗ Overlay image not found: /static/images/p/overlay-invalid/mercari.png

Solution: Ensure overlay images are processed and available in the static directory

Validation

• Slugs: Must be non-empty strings
• Padding: Must be between 0 and 50%
• Overlay width: Must be between 1 and 100%
• Images: Both base and overlay must exist before processing

Tips and Best Practices

Image Preparation

1. Process images first: Ensure all base and overlay images are processed by the Image Processor
2. Check slugs: Verify slug names match the directory names in /static/images/p/
3. Test with one: Try a single combination first to verify settings

Overlay Design

1. Use 1
   images: Overlay images should be square for best results
2. Add borders: Consider adding white/colored borders to overlay images
3. Transparent backgrounds: Overlays can use transparency if needed

Batch Processing

1. Group similar products: Process related products together
2. Consistent overlays: Use the same overlay set across product variants
3. Verify before batch: Test configuration with a small batch first

File Organization

1. Output directory: dist/ is gitignored, move files as needed
2. Naming convention: {base}--{overlay}.png makes it easy to identify combinations
3. Cleanup: Remove old files from dist/ before new batch processing

Integration with Image Processor

Image Mixer works seamlessly with the Image Processor:

1. Source images: Uses mercari.png files generated by Image Processor
2. Slug system: Follows the same slug-based directory structure
3. Image format: Compatible with processed PNG outputs

Workflow Example

# 1. Process original images
pnpm convimgs

# 2. Run image mixer
pnpm image-mixer

# 3. Use output images for marketing/listings

Troubleshooting

CLI doesn’t start

Issue: command not found or permission error

Solution:

cd sub-packages/image-mixer
chmod +x bin/image-mixer.mjs
pnpm install

Images not found

Issue: “Base image not found” errors

Solution:

1. Check if slug exists: ls static/images/p/{slug}/
2. Verify mercari.png exists: ls static/images/p/{slug}/mercari.png
3. Process images if missing: pnpm convimgs {original-filename}

Wrong positioning

Issue: Overlay appears in wrong position or size

Solution:

1. Check configuration values (padding, overlay width)
2. Verify base image dimensions are correct
3. Test with different percentage values

Output quality issues

Issue: Pixelated or low-quality output

Solution:

• Image Mixer uses Sharp with PNG output at maximum quality
• Check source images (mercari.png) are high quality (1600px width)
• Verify overlay images are high resolution

Technical Details

Dependencies

• sharp: Image processing and compositing
• prompts: Interactive CLI prompts
• chalk: Terminal color output

Architecture

sub-packages/image-mixer/
├── bin/
│   └── image-mixer.mjs      # CLI entry point
├── src/
│   └── image-processor.mjs  # Core processing logic
├── dist/                     # Output directory (gitignored)
├── package.json
└── README.md

Image Processing Pipeline

1. Load base image from /static/images/p/{base-slug}/mercari.png
2. Load overlay image from /static/images/p/{overlay-slug}/mercari.png
3. Get base dimensions using Sharp metadata
4. Calculate overlay size (width × width for 1
   ratio)
5. Calculate position (bottom-right with padding)
6. Resize overlay to calculated dimensions
7. Composite images using Sharp composite API
8. Output PNG to dist/{base}--{overlay}.png

Related Documentation

• Image Processor - Process original images to generate mercari.png files
• Sub Packages Overview - Other development tools and utilities