Skip to content
Back to search

scene-card-studio

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/swping999--scene-card-studio/badge.svg)](/listings/swping999--scene-card-studio)

HTML

<a href="/listings/swping999--scene-card-studio"><img src="/api/listings/swping999--scene-card-studio/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 544 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">Scene Card Studio</h1>
  2. <p align="center"><strong>AI visual director for turning personal photos into structured, editable visual narratives.</strong></p>
  3. <p align="center">
  4. <a href="https://github.com/swping999/scene-card-studio/releases/tag/v0.7.0"><img alt="Version 0.7.0" src="https://img.shields.io/badge/version-0.7.0-315c8c?style=flat-square"></a>
  5. <a href="https://github.com/swping999/scene-card-studio/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/swping999/scene-card-studio/ci.yml?branch=main&style=flat-square&label=tests"></a>
  6. <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-315c8c?style=flat-square">
  7. <img alt="Codex Skill" src="https://img.shields.io/badge/Codex-Skill-111827?style=flat-square">
  8. <a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-315c8c?style=flat-square"></a>
  9. </p>
  10. <p align="center"><a href="README.zh-CN.md">中文</a> · English</p>
  11. [![Scene Card Studio opening film](docs/media/scene-card-studio-opening.gif)](docs/media/scene-card-studio-opening.mp4)
  12. ▶ [Play the 6-second opening film](docs/media/scene-card-studio-opening.mp4)
  13. > **This is not a style-transfer repository. It is a Scene Card–based visual narrative engine for personal photography.**
  14. 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?*
  15. ```text
  16. photos → Scene Cards → Narrative System → Prompt Compiler → image generation → aesthetic review → retry / accept
  17. ```
  18. ### One command to start
  19. 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:
  20. ```bash
  21. scene-card-studio direct photos/portrait.jpg \
  22. --brief "a restrained hand-colored heritage portrait"
  23. ```
  24. 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.
  25. | At a glance | Project contract |
  26. | --- | --- |
  27. | Input | One photograph or a related photo sequence |
  28. | Direction | Observable evidence → editable interpretation → explicit art direction |
  29. | Visual vocabulary | 11 Narrative Systems + 23 replaceable Expression Profiles |
  30. | Output | Local workprints, versioned prompts, contract-checked images, deterministic typography, review records |
  31. | Privacy | Local-first analysis; cloud upload requires provider-, purpose-, and file-specific consent |
  32. **Explore:** [Visual Selection Guide](VISUAL-GUIDE.md) · [Before / After](#before--after) · [Visual Director](#the-visual-director-layer) · [Systems and Profiles](#current-systems-profiles-and-deterministic-typography) · [Quick start](#quick-start) · [Contributing](CONTRIBUTING.md)
  33. ### One photo or many
  34. - **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.
  35. - **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.
  36. - **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.
  37. 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.
  38. **Not sure which result to choose?** Open the [Visual Selection Guide](VISUAL-GUIDE.md) 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.
  39. ## After-only Director Gallery · v0.7
  40. 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.
  41. | Selective Material Relief | Chinese Photo Editorial | Travel Zine | Chinese Ink Poetry · with verse |
  42. | --- | --- | --- | --- |
  43. | [![Real boat with relief mountains](examples/cases/v0.7-director-gallery/after/selective-material-relief.png)](examples/cases/v0.7-director-gallery/after/selective-material-relief.png) | [![Ink-and-paper coastal photo editorial](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial.png)](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial.png) | [![Sparse travel zine railway image](examples/cases/v0.7-director-gallery/after/travel-zine.png)](examples/cases/v0.7-director-gallery/after/travel-zine.png) | [![Photographic cat and home transitioning into Chinese ink with visible poem](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-final.png)](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-final.png) |
  44. [Open the v0.7 After-only gallery and asset records](examples/cases/v0.7-director-gallery/README.md)
  45. ### Expanded profile sets · three examples each
  46. | Travel Zine | Travel Zine · Alpine | Travel Zine · Harbor |
  47. | --- | --- | --- |
  48. | [![Travel zine railway](examples/cases/v0.7-director-gallery/after/travel-zine.png)](examples/cases/v0.7-director-gallery/after/travel-zine.png) | [![Travel zine alpine lake](examples/cases/v0.7-director-gallery/after/travel-zine-alpine.png)](examples/cases/v0.7-director-gallery/after/travel-zine-alpine.png) | [![Travel zine coastal harbor](examples/cases/v0.7-director-gallery/after/travel-zine-harbor.png)](examples/cases/v0.7-director-gallery/after/travel-zine-harbor.png) |
  49. | Chinese Photo Editorial | Tea by the Window | Reading Desk |
  50. | --- | --- | --- |
  51. | [![Chinese photo editorial coast](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial.png)](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial.png) | [![Photographic tea setting with ink transition](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial-tea.png)](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial-tea.png) | [![Photographic reading desk with ink transition](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial-desk.png)](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial-desk.png) |
  52. | Selective Material Relief | Bicycle Alley | Coastal Lighthouse |
  53. | --- | --- | --- |
  54. | [![Real boat with relief mountains](examples/cases/v0.7-director-gallery/after/selective-material-relief.png)](examples/cases/v0.7-director-gallery/after/selective-material-relief.png) | [![Real bicycle with relief alley](examples/cases/v0.7-director-gallery/after/selective-material-relief-bicycle.png)](examples/cases/v0.7-director-gallery/after/selective-material-relief-bicycle.png) | [![Real lighthouse with relief coast](examples/cases/v0.7-director-gallery/after/selective-material-relief-lighthouse.png)](examples/cases/v0.7-director-gallery/after/selective-material-relief-lighthouse.png) |
  55. | Chinese Ink Poetry · Cat | Chinese Ink Poetry · Bridge | Chinese Ink Poetry · Boat |
  56. | --- | --- | --- |
  57. | [![Photographic cat with vertical verse](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-final.png)](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-final.png) | [![Photographic bridge with vertical verse](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-bridge-final.png)](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-bridge-final.png) | [![Photographic boat with vertical verse](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-boat-final.png)](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-boat-final.png) |
  58. ### Selected After Gallery · strongest material cases
  59. 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.
  60. | Relief environment | Ink editorial | Travel zine |
  61. | --- | --- | --- |
  62. | [![Real boat with relief mountains](examples/cases/v0.7-director-gallery/after/selective-material-relief.png)](examples/cases/v0.7-director-gallery/after/selective-material-relief.png) | [![Ink-and-paper coastal photo editorial](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial.png)](examples/cases/v0.7-director-gallery/after/chinese-photo-editorial.png) | [![Sparse travel zine railway image](examples/cases/v0.7-director-gallery/after/travel-zine.png)](examples/cases/v0.7-director-gallery/after/travel-zine.png) |
  63. | [![Continuous threaded lake landscape](examples/cases/v0.6-gallery/after/threaded-landscape.png)](examples/cases/v0.6-gallery/after/threaded-landscape.png) | [![Layered paper relief landscape](examples/cases/v0.6-gallery/after/paper-relief-landscape.png)](examples/cases/v0.6-gallery/after/paper-relief-landscape.png) | [![Opaque gouache place study](examples/cases/v0.6-gallery/after/gouache-place-study.png)](examples/cases/v0.6-gallery/after/gouache-place-study.png) |
  64. | [![Mineral ink bridge memory](examples/cases/v0.6-gallery/after/mineral-ink-memory.png)](examples/cases/v0.6-gallery/after/mineral-ink-memory.png) | [![Impasto lake light study](examples/cases/v0.6-gallery/after/impasto-light-study.png)](examples/cases/v0.6-gallery/after/impasto-light-study.png) | [![Cyanotype field-object archive](examples/cases/v0.6-gallery/after/cyanotype-archive.png)](examples/cases/v0.6-gallery/after/cyanotype-archive.png) |
  65. #### Chinese Ink Poetry · Guofeng
  66. 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.
  67. [![Photographic cat at its home window with source-derived ink treatment and visible poem overlay](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-final.png)](examples/cases/v0.7-director-gallery/after/chinese-ink-poetry-final.png)
  68. ## Before / After
  69. ### Landscape-led expansion
  70. 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.
  71. #### Featured Material Narratives
  72. 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.
  73. | Gouache Place Study | Sculpted Place Diorama · 3D |
  74. | --- | --- |
  75. | [![Gouache observatory place study](examples/cases/v0.6-gallery/after/gouache-place-study.png)](#gouache-place-study) | [![Sculpted three-dimensional salt-marsh diorama](examples/cases/v0.6-gallery/after/sculpted-place-diorama.png)](#sculpted-place-diorama--3d) |
  76. | **Threaded Landscape · textile relief** | **Paper Relief Landscape** |
  77. | [![Threaded textile relief of the lake and boat](examples/cases/v0.6-gallery/after/threaded-landscape.png)](#threaded-landscape--textile-relief) | [![Cut-paper relief landscape](examples/cases/v0.6-gallery/after/paper-relief-landscape.png)](#paper-relief-landscape) |
  78. #### Journey Taxonomy
  79. | Before · ordinary salt-marsh view | After · one semantic place field, not a sticker board |
  80. | --- | --- |
  81. | ![Ordinary salt-marsh boardwalk](examples/cases/v0.6-gallery/before/salt-marsh-boardwalk.png) | ![Journey Taxonomy landscape](examples/cases/v0.6-gallery/after/journey-taxonomy.png) |
  82. #### Mineral Ink Memory
  83. | Before · cluttered winter bridge | After · continuous mineral pigment and ink |
  84. | --- | --- |
  85. | ![Ordinary winter stone bridge](examples/cases/v0.6-gallery/before/stone-bridge.png) | ![Mineral ink bridge memory](examples/cases/v0.6-gallery/after/mineral-ink-memory.png) |
  86. #### Impasto Light Study
  87. | Before · flat overcast lake | After · light organized through physical paint depth |
  88. | --- | --- |
  89. | ![Ordinary mountain-lake snapshot](examples/cases/v0.6-gallery/before/mountain-lake.png) | ![Impasto mountain-lake light study](examples/cases/v0.6-gallery/after/impasto-light-study.png) |
  90. #### Pixel Diary
  91. | Before · empty market lane | After · one authored pixel grid and depth system |
  92. | --- | --- |
  93. | ![Ordinary empty market lane](examples/cases/v0.6-gallery/before/empty-market-lane.png) | ![Pixel diary market lane](examples/cases/v0.6-gallery/after/pixel-diary.png) |
  94. #### Risograph Route
  95. | Before · literal route through a marsh | After · limited-ink route rhythm |
  96. | --- | --- |
  97. | ![Ordinary salt-marsh route](examples/cases/v0.6-gallery/before/salt-marsh-boardwalk.png) | ![Risograph route print](examples/cases/v0.6-gallery/after/risograph-route.png) |
  98. #### Gouache Place Study
  99. | Before · harsh highland snapshot | After · opaque matte place painting |
  100. | --- | --- |
  101. | ![Ordinary highland observatory](examples/cases/v0.6-gallery/before/highland-observatory.png) | ![Gouache observatory place study](examples/cases/v0.6-gallery/after/gouache-place-study.png) |
  102. #### Cyanotype Archive
  103. | Before · messy field desk | After · evidence-bound contact-print study |
  104. | --- | --- |
  105. | ![Ordinary field objects on a desk](examples/cases/v0.6-gallery/before/field-desk.png) | ![Cyanotype field-object archive](examples/cases/v0.6-gallery/after/cyanotype-archive.png) |
  106. #### Paper Relief Landscape
  107. | Before · flat winter terrain | After · one physically coherent paper relief |
  108. | --- | --- |
  109. | ![Ordinary stone bridge and terraces](examples/cases/v0.6-gallery/before/stone-bridge.png) | ![Cut-paper relief landscape](examples/cases/v0.6-gallery/after/paper-relief-landscape.png) |
  110. #### Autochrome Memory
  111. | Before · casual lake stop | After · restrained early-color material memory |
  112. | --- | --- |
  113. | ![Ordinary mountain lake and boat](examples/cases/v0.6-gallery/before/mountain-lake.png) | ![Autochrome-inspired lake memory](examples/cases/v0.6-gallery/after/autochrome-memory.png) |
  114. #### Pixel + Ink Memory · experimental
  115. | Before · one photographic surface | After · near evidence in pixels, distance in ink |
  116. | --- | --- |
  117. | ![Ordinary empty market lane](examples/cases/v0.6-gallery/before/empty-market-lane.png) | ![Pixel and ink market memory](examples/cases/v0.6-gallery/after/pixel-ink-memory.png) |
  118. #### Sculpted Place Diorama · 3D
  119. | Before · flat landscape photograph | After · physical miniature topology and real volume |
  120. | --- | --- |
  121. | ![Ordinary salt-marsh boardwalk](examples/cases/v0.6-gallery/before/salt-marsh-boardwalk.png) | ![Sculpted three-dimensional salt-marsh diorama](examples/cases/v0.6-gallery/after/sculpted-place-diorama.png) |
  122. #### Threaded Landscape · textile relief
  123. | Before · flat lake snapshot | After · one continuous woven and embroidered relief |
  124. | --- | --- |
  125. | ![Ordinary mountain lake and boat](examples/cases/v0.6-gallery/before/mountain-lake.png) | ![Threaded textile relief of the lake and boat](examples/cases/v0.6-gallery/after/threaded-landscape.png) |
  126. [Inspect the 12 Scene Cards](examples/cases/v0.6-gallery/case-records.json) · [Open the recompilable evidence index](examples/cases/v0.6-gallery/evidence/index.json) · [Read the originality and case notes](examples/cases/v0.6-gallery/README.md)
  127. ## Previous v0.4 Before / After
  128. 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.
  129. ### 1 · Cinematic Sequence
  130. | Before · flat metro snapshot | After · motivated rain, light, and frame geometry |
  131. | --- | --- |
  132. | ![Unpolished metro snapshot](examples/cases/v0.4-gallery/before/cinematic-sequence.jpg) | ![Directed cinematic night frame](examples/cases/v0.4-gallery/after/cinematic-sequence.jpg) |
  133. ### 2 · Memory Atlas
  134. | Before · roadside building | After · real architecture fused with drawn geography |
  135. | --- | --- |
  136. | ![Ordinary roadside building](examples/cases/v0.4-gallery/before/memory-atlas.jpg) | ![Photographic building integrated with watercolor terrain](examples/cases/v0.4-gallery/after/memory-atlas.jpg) |
  137. ### 3 · Family Chronicle
  138. | Before · cluttered domestic snapshot | After · one intimate photographic-drawing record |
  139. | --- | --- |
  140. | ![Ordinary laundry-folding snapshot](examples/cases/v0.4-gallery/before/family-chronicle.jpg) | ![Directed family chronicle](examples/cases/v0.4-gallery/after/family-chronicle.jpg) |
  141. ### 4 · Quiet Editorial
  142. | Before · cluttered kettle photo | After · quiet material study |
  143. | --- | --- |
  144. | ![Ordinary kettle snapshot](examples/cases/v0.4-gallery/before/quiet-editorial.jpg) | ![Quiet editorial kettle photograph](examples/cases/v0.4-gallery/after/quiet-editorial.jpg) |
  145. ### 5 · Editorial Rhythm
  146. | Before · accidental chair arrangement | After · color, spacing, crop, and shadow as rhythm |
  147. | --- | --- |
  148. | ![Ordinary plastic chairs](examples/cases/v0.4-gallery/before/editorial-rhythm.jpg) | ![Directed chair rhythm](examples/cases/v0.4-gallery/after/editorial-rhythm.jpg) |
  149. ### 6 · Field Log
  150. | Before · casual repair snapshot | After · factual observational record |
  151. | --- | --- |
  152. | ![Ordinary bicycle repair snapshot](examples/cases/v0.4-gallery/before/field-log.jpg) | ![Directed field-log photograph](examples/cases/v0.4-gallery/after/field-log.jpg) |
  153. ### 7 · Watercolor Chronicle
  154. | Before · ordinary seaside portrait | After · person, clothing, objects, and place repainted together |
  155. | --- | --- |
  156. | ![Ordinary seaside portrait](examples/cases/v0.4-gallery/before/watercolor-chronicle.jpg) | ![Fully repainted watercolor chronicle](examples/cases/v0.4-gallery/after/watercolor-chronicle.jpg) |
  157. ### 8 · Heritage Portrait
  158. | Before · ordinary reading-corner snapshot | After · gentle silver-gelatin and hand-colored portrait |
  159. | --- | --- |
  160. | ![Ordinary portrait snapshot](examples/cases/v0.4-gallery/before/heritage-portrait.jpg) | ![Directed heritage portrait](examples/cases/v0.4-gallery/after/heritage-portrait.jpg) |
  161. ### 9 · Museum Catalogue
  162. | Before · object in storage clutter | After · inspectable conservation plate |
  163. | --- | --- |
  164. | ![Radio in a cluttered storage space](examples/cases/v0.4-gallery/before/museum-catalogue.jpg) | ![Museum catalogue radio plate](examples/cases/v0.4-gallery/after/museum-catalogue.jpg) |
  165. ### 10 · Travel Journal
  166. | Before · waiting-platform snapshot | After · railway space becomes a tactile route field |
  167. | --- | --- |
  168. | ![Ordinary suitcase at a station](examples/cases/v0.4-gallery/before/travel-journal.jpg) | ![Seamless travel journal image](examples/cases/v0.4-gallery/after/travel-journal.jpg) |
  169. ### 11 · Street Reportage
  170. | Before · loose rainy crosswalk frame | After · decisive monochrome public-life frame |
  171. | --- | --- |
  172. | ![Ordinary rainy crosswalk snapshot](examples/cases/v0.4-gallery/before/street-reportage.jpg) | ![Directed black-and-white street reportage](examples/cases/v0.4-gallery/after/street-reportage.jpg) |
  173. ### 12 · Fashion Editorial
  174. | Before · bland mall portrait | After · garment-led architectural frame |
  175. | --- | --- |
  176. | ![Ordinary mall portrait](examples/cases/v0.4-gallery/before/fashion-editorial.jpg) | ![Directed fashion editorial](examples/cases/v0.4-gallery/after/fashion-editorial.jpg) |
  177. ### 13 · Dream Logic
  178. | Before · child with one kite | After · one coherent impossible rule, identity locked |
  179. | --- | --- |
  180. | ![Ordinary salt-flat kite snapshot](examples/cases/v0.4-gallery/before/dream-logic.jpg) | ![Single-kite dream-logic transformation](examples/cases/v0.4-gallery/after/dream-logic.jpg) |
  181. 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.
  182. [Inspect all 13 Scene Cards and direction records](examples/cases/v0.4-gallery/case-records.json) · [Open the recompilable evidence index](examples/cases/v0.4-gallery/evidence/index.json) · [Read the case notes](examples/cases/v0.4-gallery/README.md) · [Read the design principles](DESIGN_PRINCIPLES.md)
  183. ## Earlier benchmark cases
  184. The original benchmark cases remain part of the repository and retain their manifests, bound outputs, reviews, and retry records.
  185. ### Original Memory Atlas benchmark
  186. | Before: original travel photographs | After: AI-composited Memory Atlas |
  187. | --- | --- |
  188. | ![Original photo contact sheet](examples/outputs/before-source-photos.png) | ![Photographic architecture fused with a hand-drawn memory map](examples/outputs/memory-atlas-ai-composite.png) |
  189. [Scene Cards](examples/generated-story.json) · [Prompt Manifest](examples/prompt-manifest.json) · [Render Manifest](examples/render-manifest.json) · [Accepted Review](examples/accepted-review.json)
  190. ### Original Family Archive benchmark
  191. | Before: fictional documentary inputs | After: AI-composited family record |
  192. | --- | --- |
  193. | ![Family archive source contact sheet](examples/cases/family-archive/outputs/before.png) | ![Documentary photographs fused with drawings and archive materials](examples/cases/family-archive/outputs/family-archive-ai-composite.png) |
  194. [Scene Cards](examples/cases/family-archive/story.json) · [Prompt Manifest](examples/cases/family-archive/prompt-manifest.json) · [Render Manifest](examples/cases/family-archive/render-manifest.json) · [Accepted Review](examples/cases/family-archive/accepted-review.json)
  195. ### Original Cinematic Storyboard benchmark
  196. | Before: awkward phone snapshot | After: standalone directed frame |
  197. | --- | --- |
  198. | ![Ordinary phone snapshot of a bus stop](examples/cases/cinematic-storyboard/photos/raw-bus-stop.png) | ![Directed rainy-night bus stop frame](examples/cases/cinematic-storyboard/outputs/after-bus-stop.png) |
  199. | ![Ordinary phone snapshot of a diner](examples/cases/cinematic-storyboard/photos/raw-diner.png) | ![Directed diner seen through rain](examples/cases/cinematic-storyboard/outputs/after-diner.png) |
  200. | ![Ordinary phone snapshot of a taxi](examples/cases/cinematic-storyboard/photos/raw-taxi.png) | ![Directed taxi departure frame](examples/cases/cinematic-storyboard/outputs/after-taxi.png) |
  201. [Scene Cards](examples/cases/cinematic-storyboard/story.json) · [Compiled prompts](examples/cases/cinematic-storyboard/prompt-manifest.json) · [Failed → targeted retry → accepted record](examples/cases/cinematic-storyboard/retry-example/README.md) · [Source contact sheet](examples/cases/cinematic-storyboard/outputs/before.png)
  202. ### Original Minimal Editorial benchmark
  203. | Before: cluttered household snapshot | After: standalone art-book photograph |
  204. | --- | --- |
  205. | ![Ordinary phone snapshot of a mug](examples/cases/minimal-editorial/photos/raw-mug.png) | ![Quiet editorial photograph of the same mug](examples/cases/minimal-editorial/outputs/after-mug.png) |
  206. | ![Ordinary phone snapshot of a worn chair](examples/cases/minimal-editorial/photos/raw-chair.png) | ![Sculptural editorial photograph of the same chair](examples/cases/minimal-editorial/outputs/after-chair.png) |
  207. | ![Ordinary phone snapshot of linen](examples/cases/minimal-editorial/photos/raw-linen.png) | ![Material-focused editorial photograph of the same linen](examples/cases/minimal-editorial/outputs/after-linen.png) |
  208. [Scene Cards](examples/cases/minimal-editorial/story.json) · [Compiled prompts](examples/cases/minimal-editorial/prompt-manifest.json) · [Render Manifest](examples/cases/minimal-editorial/render-manifest.json) · [Accepted Review](examples/cases/minimal-editorial/accepted-review.json) · [Source contact sheet](examples/cases/minimal-editorial/outputs/before.png)
  209. ## The Visual Director layer
  210. Scene Cards explicitly separate visible evidence from interpretation:
  211. ```json
  212. {
  213. "observation": {
  214. "subjects": ["greenhouse", "work lamp"],
  215. "dominant_gesture": "repeating window grid",
  216. "quiet_regions": ["upper evening sky"]
  217. },
  218. "interpretation": {
  219. "narrative_intent": "patient growth",
  220. "emotional_tone": ["intimate", "hopeful"],
  221. "confidence": 0.82,
  222. "method": "manually-directed example"
  223. },
  224. "direction": {
  225. "story_role": "moment",
  226. "director_note": "Treat the lamp as a sign of care, not dramatic spectacle."
  227. }
  228. }
  229. ```
  230. - **Observation** records what is visibly present.
  231. - **Interpretation** records a tentative theme and emotional reading.
  232. - **Direction** records editable role and layout decisions.
  233. - **Narrative Systems** decide how one image or a sequence can be read.
  234. 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.
  235. ## Current systems, Profiles, and deterministic typography
  236. 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.
  237. | Narrative System | Display name | Reading mechanism |
  238. | --- | --- | --- |
  239. | `cinematic-storyboard` | Cinematic Sequence | temporal continuity, motivated light, shot relationships |
  240. | `memory-atlas` | Memory Atlas | place, distance, direction, spatial memory |
  241. | `family-archive` | Family Chronicle | repeated supplied people, objects, gestures, and time |
  242. | `minimal-editorial` | Quiet Editorial | hierarchy, negative space, light, material rhythm |
  243. | `editorial-sequence` | Editorial Rhythm | sequence, scale, contrast, density, pause |
  244. | `field-log` | Field Log | observed evidence and documentary context |
  245. | `museum-catalogue` | Museum Catalogue | inspectable plates and supplied collection metadata |
  246. | `travel-journal` | Travel Journal | movement, pauses, thresholds, supplied journey evidence |
  247. | `journey-taxonomy` | Journey Taxonomy | semantic groups of visible place evidence organized into one spatial field |
  248. | `street-reportage` | Street Reportage | observed public gestures and factual sequence |
  249. | `fashion-editorial` | Fashion Editorial | pose, garment construction, crop, shot-scale rhythm |
  250. 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.
  251. | Expression Profile | Compatible Narrative Systems |
  252. | --- | --- |
  253. | `source-led` | all systems |
  254. | `rain-nocturne` | Cinematic Sequence |
  255. | `quiet-window-light` | Quiet Editorial |
  256. | `watercolor-contour` | Memory Atlas |
  257. | `watercolor-chronicle` | Memory Atlas, Family Chronicle, Museum Catalogue, Travel Journal, Journey Taxonomy |
  258. | `graphite-paper` | Family Chronicle |
  259. | `heritage-portrait` | Family Chronicle, Museum Catalogue |
  260. | `monochrome-reportage` | Street Reportage |
  261. | `dream-logic` | Memory Atlas, Fashion Editorial |
  262. | `mineral-ink-memory` | Memory Atlas, Travel Journal, Journey Taxonomy |
  263. | `impasto-light-study` | Quiet Editorial, Memory Atlas, Travel Journal, Journey Taxonomy |
  264. | `pixel-diary` | Memory Atlas, Travel Journal, Journey Taxonomy |
  265. | `risograph-route` | Memory Atlas, Travel Journal, Journey Taxonomy |
  266. | `gouache-place-study` | Memory Atlas, Travel Journal, Journey Taxonomy |
  267. | `cyanotype-archive` | Field Log, Family Chronicle, Museum Catalogue, Street Reportage |
  268. | `paper-relief-landscape` | Memory Atlas, Travel Journal, Journey Taxonomy |
  269. | `autochrome-memory` | Memory Atlas, Family Chronicle, Travel Journal, Journey Taxonomy |
  270. | `pixel-ink-memory` · experimental | Memory Atlas, Journey Taxonomy |
  271. | `sculpted-place-diorama` · 3D | Memory Atlas, Travel Journal, Journey Taxonomy |
  272. | `threaded-landscape` | Family Chronicle, Memory Atlas, Travel Journal, Journey Taxonomy |
  273. | `travel-zine` | Memory Atlas, Family Chronicle, Travel Journal, Journey Taxonomy |
  274. | `chinese-photo-editorial` | Quiet Editorial, Memory Atlas, Family Chronicle, Museum Catalogue, Travel Journal |
  275. | `chinese-ink-poetry` | Quiet Editorial, Memory Atlas, Family Chronicle, Museum Catalogue, Travel Journal, Journey Taxonomy |
  276. | `selective-material-relief` | Memory Atlas, Family Chronicle, Travel Journal, Journey Taxonomy |
  277. ### Journey Keepsake presentation
  278. `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:
  279. ```bash
  280. scene-card-studio present render-manifest.json \
  281. --style journey-keepsake \
  282. --output journey-keepsake.svg
  283. ```
  284. 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.
  285. 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.
  286. 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:
  287. ```bash
  288. scene-card-studio present render-manifest.json \
  289. --style ink-poetry \
  290. --output ink-poetry.svg
  291. ```
  292. Every compiled prompt contains the same ten modules:
  293. 1. subject fidelity;
  294. 2. explicit `must_preserve` / `may_transform` / `must_remove` rules;
  295. 3. narrative intent;
  296. 4. composition;
  297. 5. lighting and color;
  298. 6. material and surface;
  299. 7. spatial relationships;
  300. 8. text and label strategy;
  301. 9. exclusions;
  302. 10. output ratio and format.
  303. 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.
  304. 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.
  305. ## Narrative Systems, not style filters
  306. 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.
  307. ## Quick start
  308. Requires Python 3.10+. Automatic analysis and PNG rendering use Pillow.
  309. ```bash
  310. git clone https://github.com/swping999/scene-card-studio.git
  311. cd scene-card-studio
  312. python -m pip install -e .
  313. # Fast path: one photo → one prompt-ready local direction bundle
  314. scene-card-studio direct photos/portrait.jpg --brief "quiet family portrait with restrained silver-gelatin depth"
  315. # The local analyzer deliberately stops before inventing semantic evidence.
  316. scene-card-studio check scene-card-output/story.json --json
  317. # After a human or vision-capable Skill completes and verifies the Scene Cards:
  318. scene-card-studio direct photos/portrait.jpg \
  319. --brief "quiet family portrait with restrained silver-gelatin depth" \
  320. --scene-cards scene-card-output/story.json --force
  321. # Fast path: many photos → one automatically routed narrative bundle
  322. scene-card-studio direct photos/*.jpg --brief "a travel journal built from stations, tickets, and thresholds" --output-dir travel-run
  323. # Advanced staged workflow
  324. scene-card-studio analyze photos/portrait.jpg --output portrait-story.json
  325. # Complete the reported semantic fields from visual evidence before compiling for generation.
  326. scene-card-studio check portrait-story.json --json
  327. scene-card-studio profiles --system family-archive
  328. scene-card-studio compile portrait-story.json --system family-archive --expression-profile heritage-portrait --output portrait-manifest.json
  329. # Many photos → per-photo direction or multi-source synthesis
  330. scene-card-studio analyze photos/*.jpg --output story.json
  331. scene-card-studio check story.json --json
  332. scene-card-studio recommend story.json
  333. scene-card-studio compile story.json --system cinematic-storyboard --expression-profile source-led --output prompt-manifest.json
  334. scene-card-studio compile story.json --system memory-atlas --expression-profile watercolor-chronicle --output watercolor-memory-manifest.json
  335. scene-card-studio compile story.json --system museum-catalogue --expression-profile heritage-portrait --output catalogue-manifest.json
  336. scene-card-studio render story.json --style editorial-sequence --format png --output story.png
  337. scene-card-studio render story.json --style memory-atlas --format svg --output story.svg
  338. scene-card-studio render story.json --style field-log --mode workprint --format png --output notes.png
  339. scene-card-studio consent prompt-manifest.json --provider PROVIDER --purpose "presentation synthesis" --confirm --output upload-consent.json
  340. scene-card-studio bind-outputs prompt-manifest.json --result cinematic-storyboard-01=after-01.png --output render-manifest.json
  341. 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
  342. # Fill every 1–5 score after inspecting the bound image, then finalize the record:
  343. scene-card-studio review render-manifest.json assessment.json --output review.json
  344. scene-card-studio present render-manifest.json --output presentation.svg
  345. scene-card-studio retry render-manifest.json review.json --output retry-manifest.json
  346. scene-card-studio bind-outputs retry-manifest.json --result cinematic-storyboard-01=after-01-retry.png --output post-retry-render-manifest.json
  347. ```
  348. `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.
  349. 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.
  350. The repository also includes a [bilingual routing matrix](evals/direct-briefs.json) 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.
  351. ## Codex Skill
  352. The Codex Skill is included in both source checkouts and built wheels. Install it into a new Codex Skill directory, then restart Codex:
  353. ```bash
  354. scene-card-studio skill-path
  355. scene-card-studio install-skill --target ~/.codex/skills/scene-card-studio
  356. ```
  357. The install command refuses to overwrite an existing Skill directory.
  358. Then ask:
  359. ```text
  360. Use $scene-card-studio to direct this photo as a quiet hand-colored heritage portrait.
  361. ```
  362. 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.
  363. ## Originality and privacy
  364. - no third-party style assets;
  365. - no prompts copied from similarly themed repositories;
  366. - repository examples use newly generated project-owned demo assets;
  367. - the core contribution is the Scene Card + Visual Director + narrative rendering workflow;
  368. - source photos stay local unless the user explicitly chooses otherwise.
  369. See [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md) for the versioned provenance record and [example asset terms](examples/ASSET_LICENSE.md) for per-asset licensing.
  370. ## Contributing and security
  371. 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](CONTRIBUTING.md) before proposing either one.
  372. 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](SECURITY.md).
  373. ## Roadmap
  374. - richer semantic-image adapters beyond the bundled Skill workflow;
  375. - `contact-sheet` and `journey-sequence` systems;
  376. - crop-aware subject placement;
  377. - image-model adapters and queued generation;
  378. - printable PDF and social carousel renderers;
  379. - browser preview and drag-to-reorder editor;
  380. - community-authored Narrative Systems.
  381. ## License
  382. Code and repository-specific demo assets are Apache-2.0; the bundled font remains under SIL OFL 1.1. See [example asset terms](examples/ASSET_LICENSE.md).
  383. See [CHANGELOG.md](CHANGELOG.md) for release history.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.