Scene Card Studio

AI visual director for turning personal photos into structured, editable visual narratives.

中文 · English

▶ Play the 6-second opening film

This is not a style-transfer repository. It is a Scene Card–based visual narrative engine for personal photography.

Scene Card Studio turns observable photo evidence into editable narrative decisions, versioned generation prompts, directed images, and deterministic layouts. Instead of asking only what should these photos look like?, it asks how should this story be read?

photos → Scene Cards → Narrative System → Prompt Compiler → image generation → aesthetic review → retry / accept

After installation, one local command turns one photo or a related set into draft Scene Cards, an automatically routed Prompt Manifest, a clearly labelled analysis Workprint, and a run summary:

scene-card-studio direct photos/portrait.jpg \
  --brief "a restrained hand-colored heritage portrait"

Use multiple paths or a glob for a sequence. direct selects a Narrative System from the bilingual brief and selects a non-default Expression Profile only when the brief explicitly asks for it. Its local analyzer measures dimensions, orientation, palette, brightness, and saturation; it does not pretend that those statistics identify people, objects, gestures, or spatial meaning. Until those semantic fields and transformation rules are completed, the bundle is labelled needs-semantic-direction and upload consent is refused. This preparation step never uploads a source photo and never presents its Workprint as a generated After.

Explore: Visual Selection Guide · Before / After · Visual Director · Systems and Profiles · Quick start · Contributing

• One photo → one directed After. Choose a compatible Narrative System and Expression Profile, then produce one standalone After. A single photo is never forced into a contact sheet, sequence, or decorative collage.
• Many photos → one coherent story. Use per-photo direction when every source needs its own After, or choose a synthesis system when place, journey, or repeated relationships need to share one artifact.
• Style remains editable. The Narrative System controls how the image or story is read; the Expression Profile controls how it is visually expressed. A single photo can therefore use source-led, watercolor-chronicle, heritage-portrait, dream-logic, or another profile supported by the selected system.

Check compatible combinations with scene-card-studio profiles. The compiler records single-photo, multi-photo-per-source, or multi-photo-synthesis in every Manifest so downstream tools cannot silently change the requested source mode.

Not sure which result to choose? Open the Visual Selection Guide for all 11 Narrative Systems and all 24 Profiles, each with a repository example, recommended subjects, ready-to-copy brief phrases, and an explanation of automatic routing.

The public showcase leads with the finished After image. These four new cases are designed to make the visual difference obvious: a real subject with a relief environment, a restrained ink-and-paper editorial, a sparse travel-zine page, and a source-faithful Guofeng photo whose real subject and home dissolve selectively into ink before deterministic verse typography is added. Older Before/After evidence cases remain below and are not deleted.

Selective Material Relief	Chinese Photo Editorial	Travel Zine	Chinese Ink Poetry · with verse

Open the v0.7 After-only gallery and asset records

Travel Zine	Travel Zine · Alpine	Travel Zine · Harbor

Chinese Photo Editorial	Tea by the Window	Reading Desk

Selective Material Relief	Bicycle Alley	Coastal Lighthouse

Chinese Ink Poetry · Cat	Chinese Ink Poetry · Bridge	Chinese Ink Poetry · Boat

These are the most visually distinctive finished images in the repository. The complete evidence galleries remain below; this top section is intentionally curated for first-time visitors.

Relief environment	Ink editorial	Travel zine

Use chinese-ink-poetry when the desired result is explicitly Chinese/Guofeng. It works with people, pets, landscapes, architecture, interiors, vehicles, and objects: keep the photographed subject and original setting recognizable, let only source-derived peripheral regions dissolve into ink and warm paper, then add a user-supplied title and verse as deterministic vertical typography.

These new cases deliberately favor places and objects over portraits. Each Before is a newly generated, ordinary source image; each After materially rebuilds the same evidence through a distinct narrative or material system. The opening Journey Taxonomy case classifies a place by movement, landmark, water, vegetation, weather, and material—without copying the supplied social reference's palette, repeated photograph, sticker column, connector lines, or caption layout.

Four of the strongest landscape cases form a focused material family: opaque gouache, a physically sculpted miniature, continuous textile relief, and layered paper relief. Select an image to open its full Before/After case below.

Gouache Place Study	Sculpted Place Diorama · 3D
Threaded Landscape · textile relief	Paper Relief Landscape

Before · ordinary salt-marsh view	After · one semantic place field, not a sticker board

Before · cluttered winter bridge	After · continuous mineral pigment and ink

Before · flat overcast lake	After · light organized through physical paint depth

Before · empty market lane	After · one authored pixel grid and depth system

Before · literal route through a marsh	After · limited-ink route rhythm

Before · harsh highland snapshot	After · opaque matte place painting

Before · messy field desk	After · evidence-bound contact-print study

Before · flat winter terrain	After · one physically coherent paper relief

Before · casual lake stop	After · restrained early-color material memory

Before · one photographic surface	After · near evidence in pixels, distance in ink

Before · flat landscape photograph	After · physical miniature topology and real volume

Before · flat lake snapshot	After · one continuous woven and embroidered relief

Inspect the 12 Scene Cards · Open the recompilable evidence index · Read the originality and case notes

Every Before below is a newly generated, deliberately unpolished phone-style source made for this repository. Every After is a materially redirected image of that source—not the same image inside a border, contact sheet, or decorative collage. The people are fictional AI-generated subjects.

Before · flat metro snapshot	After · motivated rain, light, and frame geometry

Before · roadside building	After · real architecture fused with drawn geography

Before · cluttered domestic snapshot	After · one intimate photographic-drawing record

Before · cluttered kettle photo	After · quiet material study

Before · accidental chair arrangement	After · color, spacing, crop, and shadow as rhythm

Before · casual repair snapshot	After · factual observational record

Before · ordinary seaside portrait	After · person, clothing, objects, and place repainted together

Before · ordinary reading-corner snapshot	After · gentle silver-gelatin and hand-colored portrait

Before · object in storage clutter	After · inspectable conservation plate

Before · waiting-platform snapshot	After · railway space becomes a tactile route field

Before · loose rainy crosswalk frame	After · decisive monochrome public-life frame

Before · bland mall portrait	After · garment-led architectural frame

Before · child with one kite	After · one coherent impossible rule, identity locked

The first ten entries are Narrative Systems. Watercolor Chronicle, Heritage Portrait, and Dream Logic are replaceable Expression Profiles applied through compatible systems. This keeps story structure separate from surface language.

Inspect all 13 Scene Cards and direction records · Open the recompilable evidence index · Read the case notes · Read the design principles

The original benchmark cases remain part of the repository and retain their manifests, bound outputs, reviews, and retry records.

Before: original travel photographs	After: AI-composited Memory Atlas

Scene Cards · Prompt Manifest · Render Manifest · Accepted Review

Before: fictional documentary inputs	After: AI-composited family record

Scene Cards · Prompt Manifest · Render Manifest · Accepted Review

Before: awkward phone snapshot	After: standalone directed frame

Scene Cards · Compiled prompts · Failed → targeted retry → accepted record · Source contact sheet

Before: cluttered household snapshot	After: standalone art-book photograph

Scene Cards · Compiled prompts · Render Manifest · Accepted Review · Source contact sheet

Scene Cards explicitly separate visible evidence from interpretation:

{
  "observation": {
    "subjects": ["greenhouse", "work lamp"],
    "dominant_gesture": "repeating window grid",
    "quiet_regions": ["upper evening sky"]
  },
  "interpretation": {
    "narrative_intent": "patient growth",
    "emotional_tone": ["intimate", "hopeful"],
    "confidence": 0.82,
    "method": "manually-directed example"
  },
  "direction": {
    "story_role": "moment",
    "director_note": "Treat the lamp as a sign of care, not dramatic spectacle."
  }
}

• Observation records what is visibly present.
• Interpretation records a tentative theme and emotional reading.
• Direction records editable role and layout decisions.
• Narrative Systems decide how one image or a sequence can be read.

The distinction prevents inferred meaning from being presented as photographic fact. Automatic analysis remains conservative, and every Scene Card decision can be edited before prompt compilation.

The compiler turns Scene Card evidence, one Narrative System, and one replaceable Expression Profile into a versioned JSON generation contract. Eleven Narrative Systems are supported. The system defines how the story is read; the Profile defines how that mechanism is visually expressed. source-led remains the default.

Twenty-three replaceable Profiles are available beyond the default source-led. They include material, photographic, editorial, Guofeng ink-poetry, and spatial-relief languages. pixel-ink-memory is explicitly experimental. The v0.3.3 name full-watercolor-memory remains a compatibility alias for watercolor-chronicle inside Memory Atlas and is not counted separately.

Journey Keepsake is a deterministic presentation mode, not another image style. It places one accepted After inside an original asymmetric collector sheet with a side provenance stub and only user-supplied captions, locations, dates, collection data, and notes:

scene-card-studio present render-manifest.json \
  --style journey-keepsake \
  --output journey-keepsake.svg

It does not generate a second image, change candidate pixels, reproduce an upper/lower comparison, or borrow sample slogans and layout proportions from a reference prompt.

Visible text is no longer delegated to the image model. Every Manifest includes a presentation_contract; scene-card-studio present applies only supplied captions, dates, locations, collection names, and catalogue identifiers as a deterministic SVG overlay. Missing metadata is omitted rather than inferred.

For Guofeng poem layouts, use --style ink-poetry; the poem must come from the user's Scene Card caption and is never generated inside the image pixels:

scene-card-studio present render-manifest.json \
  --style ink-poetry \
  --output ink-poetry.svg

Every compiled prompt contains the same ten modules:

1. subject fidelity;
2. explicit must_preserve / may_transform / must_remove rules;
3. narrative intent;
4. composition;
5. lighting and color;
6. material and surface;
7. spatial relationships;
8. text and label strategy;
9. exclusions;
10. output ratio and format.

Every prompt now carries a structured output_contract with exact MIME type, width, height, and aspect ratio. bind-outputs decodes the candidate and rejects format or dimension mismatches before review. Candidate paths are stored relative to the Render Manifest so bundles remain portable. Formal review reopens and re-hashes the current files; replacing an image after binding invalidates the review. Optional reference_output records are benchmark comparisons only: a formal review must target a Render Manifest containing candidate_output records.

Sequence systems additionally review subject continuity, light/color continuity, rhythm, and narrative arc. Retry provenance is a closed hash chain: Prompt Manifest → failed Render Manifest → failed Review → Retry Manifest → post-retry Render Manifest → accepted Review. Each link records its parent hash and chronology.

The project expands through recording and reading mechanisms, not a flat menu of visual effects. Watercolor, heritage photographic process, monochrome treatment, and dream logic remain replaceable Profiles. A system must explain what narrative work it performs; a list of aesthetic keywords is not enough.

Requires Python 3.10+. Automatic analysis and PNG rendering use Pillow.

git clone https://github.com/swping999/scene-card-studio.git
cd scene-card-studio
python -m pip install -e .

# Fast path: one photo → one prompt-ready local direction bundle
scene-card-studio direct photos/portrait.jpg --brief "quiet family portrait with restrained silver-gelatin depth"

# The local analyzer deliberately stops before inventing semantic evidence.
scene-card-studio check scene-card-output/story.json --json

# After a human or vision-capable Skill completes and verifies the Scene Cards:
scene-card-studio direct photos/portrait.jpg \
  --brief "quiet family portrait with restrained silver-gelatin depth" \
  --scene-cards scene-card-output/story.json --force

# Fast path: many photos → one automatically routed narrative bundle
scene-card-studio direct photos/*.jpg --brief "a travel journal built from stations, tickets, and thresholds" --output-dir travel-run

# Advanced staged workflow
scene-card-studio analyze photos/portrait.jpg --output portrait-story.json
# Complete the reported semantic fields from visual evidence before compiling for generation.
scene-card-studio check portrait-story.json --json
scene-card-studio profiles --system family-archive
scene-card-studio compile portrait-story.json --system family-archive --expression-profile heritage-portrait --output portrait-manifest.json

# Many photos → per-photo direction or multi-source synthesis
scene-card-studio analyze photos/*.jpg --output story.json
scene-card-studio check story.json --json
scene-card-studio recommend story.json
scene-card-studio compile story.json --system cinematic-storyboard --expression-profile source-led --output prompt-manifest.json
scene-card-studio compile story.json --system memory-atlas --expression-profile watercolor-chronicle --output watercolor-memory-manifest.json
scene-card-studio compile story.json --system museum-catalogue --expression-profile heritage-portrait --output catalogue-manifest.json
scene-card-studio render story.json --style editorial-sequence --format png --output story.png
scene-card-studio render story.json --style memory-atlas --format svg --output story.svg
scene-card-studio render story.json --style field-log --mode workprint --format png --output notes.png
scene-card-studio consent prompt-manifest.json --provider PROVIDER --purpose "presentation synthesis" --confirm --output upload-consent.json
scene-card-studio bind-outputs prompt-manifest.json --result cinematic-storyboard-01=after-01.png --output render-manifest.json
scene-card-studio review-template render-manifest.json --reviewer-type human --reviewer-name "YOUR NAME" --reviewer-model "visual inspection" --method "full-resolution comparison" --output assessment.json
# Fill every 1–5 score after inspecting the bound image, then finalize the record:
scene-card-studio review render-manifest.json assessment.json --output review.json
scene-card-studio present render-manifest.json --output presentation.svg
scene-card-studio retry render-manifest.json review.json --output retry-manifest.json
scene-card-studio bind-outputs retry-manifest.json --result cinematic-storyboard-01=after-01-retry.png --output post-retry-render-manifest.json

direct writes story.json, prompt-manifest.json, workprint.svg, and run-summary.json into a dedicated output directory. It refuses accidental overwrites unless --force is explicit. check reports the exact semantic fields that remain incomplete. A prepared story may re-enter the same flow through --scene-cards; its source list must match the supplied photos exactly, and low-level image measurements are refreshed from the files. For one photo, every system emits exactly one standalone prompt and labels the Manifest single-photo; no sequence continuity or invented adjacent scene is requested. For multiple photos, Cinematic, Quiet Editorial, Editorial Rhythm, Field Log, Museum, Street, and Fashion emit one prompt per source, while Memory Atlas, Family Chronicle, Travel Journal, and Journey Taxonomy emit one synthesis prompt.

Cloud synthesis requires explicit consent containing the provider, purpose, and exact upload list. Missing or incomplete direction-readiness evidence fails closed. Formal review refuses an unbound Prompt Manifest, and retry refuses an unfinished or accepted review. present verifies bound output hashes, writes portable relative image references, and keeps generated pixels separate from deterministic text. Raster analysis, output binding, and safe SVG embedding enforce source-byte and pixel limits.

The repository also includes a bilingual routing matrix with positive, negated, and ambiguous briefs. CI checks all eleven Narrative Systems, all non-default Profiles, single-photo contracts, multi-photo modes, semantic readiness, formal review, retry provenance, safe image embedding, recompilable gallery evidence, and pixel-level visual difference across every published Before/After pair.

The Codex Skill is included in both source checkouts and built wheels. Install it into a new Codex Skill directory, then restart Codex:

scene-card-studio skill-path
scene-card-studio install-skill --target ~/.codex/skills/scene-card-studio

The install command refuses to overwrite an existing Skill directory.

Then ask:

Use $scene-card-studio to direct this photo as a quiet hand-colored heritage portrait.

The Skill uses the same local direct bundle first, completes semantic Scene Card evidence through visual inspection, verifies it with check, then asks for provider-, purpose-, and file-specific consent before any remote image generation.

• no third-party style assets;
• no prompts copied from similarly themed repositories;
• repository examples use newly generated project-owned demo assets;
• the core contribution is the Scene Card + Visual Director + narrative rendering workflow;
• source photos stay local unless the user explicitly chooses otherwise.

See DESIGN_PRINCIPLES.md for the versioned provenance record and example asset terms for per-asset licensing.

New Narrative Systems must introduce a distinct way of reading one photo or a photo sequence; new Expression Profiles must remain replaceable and may not imitate a named creator or reuse third-party visual assets. Read CONTRIBUTING.md before proposing either one.

Please report suspected path traversal, unintended photo disclosure, manifest spoofing, unsafe image handling, prompt injection, or credential exposure through the repository's private security-reporting channel. See SECURITY.md.

• richer semantic-image adapters beyond the bundled Skill workflow;
• contact-sheet and journey-sequence systems;
• crop-aware subject placement;
• image-model adapters and queued generation;
• printable PDF and social carousel renderers;
• browser preview and drag-to-reorder editor;
• community-authored Narrative Systems.

Code and repository-specific demo assets are Apache-2.0; the bundled font remains under SIL OFL 1.1. See example asset terms.

See CHANGELOG.md for release history.