Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Clarify character sheet rear view conditioning

Bittif36ef57ddc13
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index a7a74d1..6668e4a 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -30,6 +30,7 @@ This alpha update adds Linux support, LAN generation workers, expanded color gra
## Fixes and improvements
+- Character sheets give side and back views explicit orientation instructions, keeping reference identity and clothing without copying the front-facing pose.
- The Add effect menu lists effects alphabetically.
- Renamed the Look effect to Opacity and removed its Temperature control. Temperature adjustment is available in Basic Corrections.
- New empty images created while browsing child images stay in the same image family.
diff --git a/src/lib/characterSheet.test.ts b/src/lib/characterSheet.test.ts
index 14c050e..f71ab29 100644
--- a/src/lib/characterSheet.test.ts
+++ b/src/lib/characterSheet.test.ts
@@ -8,7 +8,7 @@ import { createProjectConfig, parseProjectConfig, type ProjectRecord } from "./p
import { cancelSlopfabGeneration, enqueueSlopfabGeneration, resolveSlopfabPlan } from "./runtime";
import { EMPTY_ENGINE_SETTINGS, type GeneratorTemplate } from "./settings";
import { WorkQueue } from "./workQueue";
-import { CHARACTER_SHEET_HEIGHTS, characterSheetDimensions } from "./characterSheet";
+import { CHARACTER_SHEET_HEIGHTS, characterSheetDimensions, compileCharacterSheet } from "./characterSheet";
vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
@@ -71,6 +71,13 @@ it.each([false, true])("uses a shared front-view outfit with square portrait and
expect(request.prompt).toContain(["frontal upper-body shot framed from the waist up", "full body front view", "full body side view", "full body back view"][viewIndex]);
expect(request.prompt).toContain("clothing, footwear, accessories");
expect(request.prompt).toContain("<Picture 1>");
+ expect(request.prompt).toContain("<Subject 1> (appears in [Shot 1]): partially_preserved");
+ if (viewIndex === 3) {
+ expect(request.prompt).toContain("The camera is directly behind the character");
+ expect(request.prompt).toContain("The face, eyes and front of the chest are hidden");
+ expect(request.prompt).toContain("Rotate the character 180 degrees from the wardrobe reference");
+ expect(request.prompt).not.toContain("requested side or back view");
+ }
expect(request.prompt).not.toContain("A still photograph");
expect(session.getSnapshot().config.assets).toEqual(original.assets);
if (changed && index === 0) session.update((current) => ({ ...current, imageScene: { ...current.imageScene!, nodes: current.imageScene!.nodes.map((node) => ({ ...node, description: "Changed during generation" })) } }));
@@ -126,6 +133,29 @@ it("rejects unsupported sheet heights before queueing generation", () => {
expect(queue.getSnapshot()).toHaveLength(0);
});
+it("keeps the required rear orientation after template instructions and in reference retention", () => {
+ const { session } = setup();
+ const config = session.getSnapshot().config;
+ const snapshot = structuredClone(config);
+ const views = compileCharacterSheet(config, config.assets[0], "cache/front.png", {
+ prompt: "Wear a red coat with a chest badge, looking straight at the camera.",
+ });
+ const back = views[3].prompt;
+ const retention = back.split("retention_analysis:\n")[1].split("\n\ndetailed_description:")[0];
+ expect(retention).toContain("partially_preserved");
+ expect(retention).toContain("replace the reference pose, gaze, camera angle and framing");
+ expect(retention).toContain("A full body back view");
+ expect(retention).not.toContain("fully_preserved");
+ const afterTemplate = back.slice(back.indexOf("Template instructions:"));
+ expect(afterTemplate).toContain("takes precedence over reference poses and template pose or framing instructions");
+ expect(afterTemplate).toContain("The face, eyes and front of the chest are hidden");
+ expect(back).toContain("without moving front closures or front graphics onto its back");
+ expect(back).not.toContain("Retain the same facial features wherever visible");
+ expect(views[2].prompt).toContain("head, shoulders, torso, hips and feet all face left");
+ expect(views[1].prompt).toContain("Retain the same facial features wherever visible");
+ expect(config).toEqual(snapshot);
+});
+
it.each([0, 12345, -1])("uses template steps and seed %s for every view and saved settings", async (seed) => {
const { queue, session } = setup();
const original = structuredClone(session.getSnapshot().config.imageScene);
diff --git a/src/lib/characterSheet.ts b/src/lib/characterSheet.ts
index 4f2516b..a9995f8 100644
--- a/src/lib/characterSheet.ts
+++ b/src/lib/characterSheet.ts
@@ -6,8 +6,8 @@ import type { ProjectAsset, ProjectConfig, ProjectReference } from "./project";
export const CHARACTER_SHEET_VIEWS = [
{ label: "Upper body front", description: "A frontal upper-body shot framed from the waist up, looking straight at the camera. Include the entire head, both shoulders, arms and torso down to the waist, clearly showing the upper-body clothing. Do not crop tightly around the face or shoulders." },
{ label: "Full body front", description: "A full body front view, facing directly toward the camera, standing in a neutral pose. Show the entire figure from head to feet without cropping." },
- { label: "Full body side", description: "A full body side view, in strict left-facing profile, standing in a neutral pose. Show the entire figure from head to feet without cropping." },
- { label: "Full body back", description: "A full body back view, facing directly away from the camera, standing in a neutral pose. Show the entire figure from head to feet without cropping." },
+ { label: "Full body side", description: "A full body side view, in strict left-facing profile, standing in a neutral pose. The head, shoulders, torso, hips and feet all face left, perpendicular to the camera. Show only the profile, with no turn toward the camera or three-quarter angle. Show the entire figure from head to feet without cropping." },
+ { label: "Full body back", description: "A full body back view, facing directly away from the camera, standing in a neutral pose. The camera is directly behind the character: show the back of the head, back of the shoulders and outfit, and the heels. The head, torso, hips and feet all face away together. The face, eyes and front of the chest are hidden. No head turn, over-the-shoulder look, profile or three-quarter angle. Show the entire figure from head to feet without cropping." },
] as const;
// Establish the complete outfit before asking for any other camera angle.
@@ -32,21 +32,25 @@ export function compileCharacterSheet(config: ProjectConfig, source: ProjectAsse
while (config.references.some((reference) => reference.id === sourceReferenceId)) sourceReferenceId += "-source";
const reference: ProjectReference = {
id: sourceReferenceId, kind: "text", name: source.name,
- description: "The character in the source image. Preserve the exact identity, facial features, body proportions, skin tone, hairstyle and hair color. Preserve clothing, footwear, accessories, materials and colors unless the template instructions explicitly change them. Preserve the source's visual medium and rendering style.",
+ description: "The character in the source image. Preserve the exact identity, body proportions, skin tone, hairstyle and hair color. Preserve clothing, footwear, accessories, materials and colors unless the template instructions explicitly change them. Preserve the source's visual medium and rendering style. The reference pose, gaze, camera angle and framing are not to be copied; use the required output view.",
intendedUse: ["character"], createdAt: source.createdAt,
images: [{ id: "character-sheet-source-image", name: source.name, relativePath: source.relativePath, sourcePath: source.sourcePath }],
};
return CHARACTER_SHEET_VIEWS.map((view, index) => {
const wardrobe = index === 1
? "Apply the template's clothing instructions and references to establish the outfit. Where no change is requested, copy visible garments from <Picture 1> exactly. For clothing outside its crop, complete one coherent outfit for this character; this full body front view will define the outfit for all other views."
- : "<Picture 1> is the original identity reference. <Picture 2> is the full body front view of this same character and the fixed wardrobe reference. Reproduce that exact outfit from the requested camera angle. Keep identical garment types, layers, cuts, lengths, fit, seams, closures, patterns, colors, fabric, footwear, jewelry and accessories. Do not add, remove, replace, restyle or recolor any clothing. Preserve anatomical left/right placement of asymmetric details when turning the character. Infer only hidden surfaces consistently with the same garments." + (index === 0 ? " Use frontal waist-up framing while retaining the exact visible upper-body clothing." : " Change the camera angle from <Picture 2> to the requested side or back view.");
- const selectedReference = index === 1 ? reference : { ...reference, images: [...reference.images!, { id: "character-sheet-front", name: "Full body front wardrobe reference", relativePath: frontRelativePath }] };
+ : "<Picture 1> is the original identity reference. <Picture 2> is the full body front view of this same character and the fixed wardrobe reference. Use it for outfit design only, not its pose, gaze or camera angle. Reproduce that exact outfit from the requested camera angle. Keep identical garment types, layers, cuts, lengths, fit, seams, closures, patterns, colors, fabric, footwear, jewelry and accessories. Do not add, remove, replace, restyle or recolor any clothing. Preserve anatomical left/right placement of asymmetric details when turning the character. Infer hidden surfaces consistently with the same garments; details on the front stay on the front and need not be visible from other angles." + (index === 0 ? " Use frontal waist-up framing while retaining the exact visible upper-body clothing." : index === 2 ? " Rotate the character into the required strict left-facing profile." : " Rotate the character 180 degrees from the wardrobe reference into the required straight rear view. Show the back of the outfit, without moving front closures or front graphics onto its back.");
+ const orientation = `Required output view (takes precedence over reference poses and template pose or framing instructions): ${view.description}`;
+ const selectedReference = { ...reference,
+ description: `${reference.description} ${index === 3 ? "Identity must remain recognizable from the rear silhouette, hair and outfit; facial features are out of view." : "Retain the same facial features wherever visible from the required angle."} ${orientation}`,
+ images: index === 1 ? reference.images : [...reference.images!, { id: "character-sheet-front", name: "Full body front wardrobe reference", relativePath: frontRelativePath }],
+ };
const instructions = options.prompt.trim() ? `Template instructions: ${options.prompt.trim()}` : "";
- const scene = createImageScene(`Create a character reference view of @[ref:${reference.id}]. ${view.description} ${wardrobe} Preserve the character's identity. Use a plain light gray background and soft even studio lighting unless the template instructions specify otherwise. Render no text, labels, borders, additional characters or multiple views. Match the source image's visual style.\n${instructions}`);
+ const scene = createImageScene(`Create a character reference view of @[ref:${reference.id}]. ${view.description} ${wardrobe} Preserve the character's identity. Use a plain light gray background and soft even studio lighting unless the template instructions specify otherwise. Render no text, labels, borders, additional characters or multiple views. Match the source image's visual style.\n${instructions}\n${orientation}`);
scene.style = { mode: "art", medium: "the same visual medium and rendering style as <Picture 1>", aesthetics: "", lighting: "", detail: "" };
return compileImagePrompt({
...config, settings: { ...config.settings, defaultLook: null }, references: [selectedReference, ...config.references],
imageScene: scene,
- });
+ }, { referenceTransformations: { [reference.id]: `Retain identity, body proportions, hair, clothing and visual style, but replace the reference pose, gaze, camera angle and framing. ${orientation}` } });
});
}
diff --git a/src/lib/imagePrompt.test.ts b/src/lib/imagePrompt.test.ts
index 1f303e9..a1f5824 100644
--- a/src/lib/imagePrompt.test.ts
+++ b/src/lib/imagePrompt.test.ts
@@ -6,6 +6,21 @@ import fixture from "../../fixtures/project-v1-image.json";
const photo = () => createProjectConfig({ name: "Portrait", generationType: "image", prompt: "A runner suspended mid-stride", aspectRatio: "1:1", resolution: "768p", targetDurationSeconds: 60 });
describe("MiniMax H3 still-image prompts", () => {
+ it("limits a pose transformation to its named reference and preserves ordinary retention by default", () => {
+ const config = photo();
+ config.references = [
+ { id: "runner", kind: "image", name: "Runner", description: "Blue uniform", relativePath: "references/runner.png", intendedUse: ["character"], createdAt: config.createdAt },
+ { id: "coat", kind: "image", name: "Coat", description: "Red coat", relativePath: "references/coat.png", intendedUse: ["clothing"], createdAt: config.createdAt },
+ ];
+ config.imageScene!.nodes[0].description = "Show @[ref:runner] from behind wearing @[ref:coat].";
+ const ordinary = compileImagePrompt(config);
+ const transformed = compileImagePrompt(config, { referenceTransformations: { runner: "Keep identity and outfit; show the character from behind." } });
+ expect(transformed.prompt).toContain("<Subject 1> (appears in [Shot 1]): partially_preserved - Keep identity and outfit; show the character from behind.");
+ expect(transformed.prompt).toContain("<Subject 2> (appears in [Shot 1]): fully_preserved");
+ expect(ordinary.prompt).toContain("<Subject 1> (appears in [Shot 1]): fully_preserved");
+ expect(transformed.references).toEqual(ordinary.references);
+ expect(compileImagePrompt(config)).toEqual(ordinary);
+ });
it("accepts frames selected from videos as still-image references", () => {
const config = photo();
config.references = [{ id: "video", name: "Runner", kind: "video", sourcePath: "C:/runner.mp4", description: "", intendedUse: [], createdAt: config.createdAt,
diff --git a/src/lib/imagePrompt.ts b/src/lib/imagePrompt.ts
index e4a99bc..60da0fe 100644
--- a/src/lib/imagePrompt.ts
+++ b/src/lib/imagePrompt.ts
@@ -4,7 +4,7 @@ import { SHOT_TAG_GROUPS } from "./shot-tags";
/** Shared by generation and Debug Prompt. H3's base three-field / reference
* six-section contracts still apply to a single silent image. */
-export function compileImagePrompt(config: ProjectConfig) {
+export function compileImagePrompt(config: ProjectConfig, options: { referenceTransformations?: Readonly<Record<string, string>> } = {}) {
const scene = config.imageScene ?? createImageScene(config.brief.prompt);
// Only the references the prompt cites as @[ref:<id>] go to the generation.
const references = actionReferenceIds(imageScenePromptText(scene)).map((id) => {
@@ -45,7 +45,12 @@ export function compileImagePrompt(config: ProjectConfig) {
prompt: [`integrated_multimodal_description: [Shot 1] ${visual.style}\n${visual.composition}`, ...audio].join("\n\n"), references,
};
const definitions = subjects.map((subject, index) => `${label(index)} is ${subject.name}, providing ${subject.role}${subject.source}. ${subject.description}`);
- const retention = subjects.map((subject, index) => `${label(index)} (appears in [Shot 1]): fully_preserved - retain the referenced ${subject.role} of ${subject.name} while following the requested composition and styling.`);
+ const retention = subjects.map((subject, index) => {
+ const transformation = options.referenceTransformations?.[subject.id];
+ return transformation
+ ? `${label(index)} (appears in [Shot 1]): partially_preserved - ${transformation}`
+ : `${label(index)} (appears in [Shot 1]): fully_preserved - retain the referenced ${subject.role} of ${subject.name} while following the requested composition and styling.`;
+ });
if (editing) {
definitions.unshift("<Picture 1> is the original source image and composition anchor for the edited still keyframe in [Shot 1], providing the framing, perspective, environment, lighting and visual style.");
retention.unshift("<Picture 1> ([Shot 1] edited keyframe): partially_preserved - retain its composition and visual characteristics except for the described change. Preserve all other content, including any previously completed edits.");