Smell Image Generation Guide

This document explains how to generate visual images from smell information in The Tale of Genji.

Overview

The scripts/generate-smell-images.ts script automatically generates images in the style of Genji Monogatari Emaki using DALL-E 3 from extracted smell information.

Requirements

Prerequisites

Node.js (v18 or higher recommended)
TypeScript
Azure OpenAI DALL-E 3 API access
Sharp (image processing library)

Environment Variables

Set the following environment variables in your .env file:

AZURE_IMAGE_ENDPOINT=https://your-resource.openai.azure.com
AZURE_IMAGE_API_KEY=your-api-key

Installation

Install required packages:

npm install axios sharp dotenv
npm install --save-dev @types/node typescript

Usage

Basic Execution

# Run directly with TypeScript
npx tsx scripts/generate-smell-images.ts --generate

Options

1. Limit Count

# Process only first 10 items
npx tsx scripts/generate-smell-images.ts --generate --limit 10

2. Specify Volume

# Process only Volume 1
npx tsx scripts/generate-smell-images.ts --generate --vol 01

3. Combination

# First 5 items of Volume 2
npx tsx scripts/generate-smell-images.ts --generate --vol 02 --limit 5

Image Generation Specifications

Generation Parameters

Size: 1024x1024 pixels
Quality: HD (high quality)
Style: Vivid
Output Format: WebP (after conversion)
Compression Quality: 80%

Prompt Structure

Image generation prompts consist of:

const baseStyle = `
  Genji Monogatari Emaki style,
  Heian period,
  Yamato-e technique,
  Delicate line art,
  Pale colors,
  Elegant and fantastical,
  Graceful atmosphere,
  Poetic beauty,
  Heian aristocrat mansion,
  Shinden-zukuri interior,
  Space with curtains and blinds
`;

Prompt Generation Example

This lord was not accustomed to this fragrance, so the feeling of
considering him as her own, with a noble sentiment, was boundless.
Smell quality: graceful, beautiful.
Genji Monogatari Emaki style, Heian period, Yamato-e technique,
delicate line art, pale colors, elegant and fantastical,
graceful atmosphere, poetic beauty, Heian aristocrat mansion,
Shinden-zukuri interior, space with curtains and blinds

Processing Flow

1. Data Loading

Load smell information from src/data/smells-index.json
Filter by specified conditions

2. Image Generation

For each smell information:

Prompt Generation: Modern translation + quality + base style
DALL-E 3 API Call: Retrieve image URL
Image Download: Temporarily save as PNG
WebP Conversion: Compress and convert with Sharp
Metadata Storage: Record in images.json

3. Progress Management

Save generation status to public/images/smells/images.json
Skip already generated images
Record error information

4. Rate Limiting

3-second wait after each generation
Processing speed considering API limits

Output

File Structure

public/images/smells/
├── 01-06-01.webp       # Generated image
├── 01-07-01.webp
├── ...
└── images.json         # Metadata

Metadata Format

{
  "01-06-01": {
    "smell": {
      "id": "01-06-01",
      "Smell_Word": "御にほひ",
      "Sentence_ModernJapanese": "..."
    },
    "imageUrl": "https://...",
    "localPath": "/path/to/01-06-01.webp",
    "status": "completed",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Status

completed: Generation completed
failed: Generation failed
Error information recorded in error field

Performance and Cost

Processing Time

Approximately 5-10 seconds per image
100 items take about 10-20 minutes

API Cost (DALL-E 3)

HD quality, 1024x1024: $0.080/image
100 items cost approximately $8.00

Storage

WebP format: approximately 100-300KB/image
1000 items: approximately 100-300MB

Troubleshooting

Common Errors

API Authentication Error

Error: AZURE_IMAGE_API_KEY environment variable is not set

→ Check .env file

Image Generation Failure
```
Error generating image: [details]
```
→ Adjust if prompt is too long → Check API limits
WebP Conversion Error
```
Error: Sharp conversion failed
```
→ Reinstall Sharp: npm install sharp

Retry

Regenerate only failed images:

# Process only status="failed" in images.json
npx tsx scripts/generate-smell-images.ts --generate --retry-failed

Best Practices

1. Gradual Generation

For large batches, generate gradually:

# Test with 10 items first
npx tsx scripts/generate-smell-images.ts --generate --limit 10

# Process all if no issues
npx tsx scripts/generate-smell-images.ts --generate

2. Process by Volume

# Volume 1
npx tsx scripts/generate-smell-images.ts --generate --vol 01

# Volume 2
npx tsx scripts/generate-smell-images.ts --generate --vol 02

3. Check Progress

# Check generation status summary
cat public/images/smells/images.json | jq 'to_entries | map(.value.status) | group_by(.) | map({status: .[0], count: length})'

Customization

Adjust Prompts

Edit generatePrompt function to change style:

const baseStyle = 'your preferred style';

Change Image Size

size: '1792x1024',  // Wide size

Adjust Quality

quality: 'standard',  // Cost reduction