Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Keep character sheet outfits consistent

Bitti7d72321eed1c
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 9bbb1ef..bddd6b3 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -4,7 +4,7 @@ This alpha update adds DMAD LoRA support, resumable model downloads, and improve
## What's new
-- Generate a character sheet from the Image toolbar's Template menu: four matching views of the selected image, combined into one PNG in the image bar.
+- Generate a character sheet from the Image toolbar's Template menu: a square portrait and three 9:16 full-body views, combined into one PNG in the image bar. The front view provides a shared clothing reference for the other views.
- Continue scenes from a selected scene's saved latents, with adjustable overlap and a choice of beginning or end. This replaces Previous scene in First & last frame.
- Export any reference with images, a video or a sound as a refmod `.safetensors` file from References. Exported refmods can be attached to other references and projects.
- Copying or cutting prompts preserves reference chips when pasted into other prompt fields.
diff --git a/src-tauri/src/commands/character_sheet.rs b/src-tauri/src/commands/character_sheet.rs
index 6583e22..04b93b1 100644
--- a/src-tauri/src/commands/character_sheet.rs
+++ b/src-tauri/src/commands/character_sheet.rs
@@ -58,7 +58,7 @@ fn write_view(
crate::storage::atomic::write_atomically(&directory.join(format!("{index}.png")), &png)
}
-/// The four independent renders are assembled losslessly, in view order.
+/// Assemble a square portrait and three tall views without stretching or cropping.
#[tauri::command]
pub(crate) fn combine_character_sheet(
folder_path: String,
@@ -66,23 +66,31 @@ pub(crate) fn combine_character_sheet(
) -> Result<super::artifacts::GeneratedImageFile, String> {
let root = ProjectRoot::open(&folder_path)?;
let directory = cache_directory(&sheet_id)?;
- let mut sheet: Option<RgbaImage> = None;
+ let mut views = Vec::new();
+ let mut total_width = 0;
+ let mut common_height = 0;
for index in 0..4 {
let path = root.existing(&format!("{directory}/{index}.png"))?;
let (width, height) = image::image_dimensions(&path).map_err(|error| error.to_string())?;
if width == 0 || width > 2048 || height == 0 || height > 8192 {
return Err("Invalid character sheet view dimensions.".into());
}
- let canvas = sheet.get_or_insert_with(|| RgbaImage::new(width * 4, height));
- if canvas.width() != width * 4 || canvas.height() != height {
- return Err("Character sheet views must have matching dimensions.".into());
+ if index > 0 && common_height != height {
+ return Err("Character sheet views must have matching heights.".into());
}
+ common_height = height;
+ total_width += width;
+ views.push((path, width));
+ }
+ let mut sheet = RgbaImage::new(total_width, common_height);
+ let mut x = 0;
+ for (path, width) in views {
let view = image::open(path)
.map_err(|error| error.to_string())?
.to_rgba8();
- image::imageops::replace(canvas, &view, i64::from(index * width), 0);
+ image::imageops::replace(&mut sheet, &view, x, 0);
+ x += i64::from(width);
}
- let sheet = sheet.ok_or("The character sheet has no views.")?;
super::artifacts::write_generated_png_frame(
&folder_path,
&sheet_id,
@@ -128,16 +136,29 @@ mod tests {
[255, 255, 0, 255],
];
for (index, color) in colors.iter().enumerate() {
- write_view(&path, "sheet-test", index, 2, 3, &color.repeat(6)).unwrap();
+ let width = if index == 0 { 16 } else { 9 };
+ write_view(
+ &path,
+ "sheet-test",
+ index,
+ width,
+ 16,
+ &color.repeat(width as usize * 16),
+ )
+ .unwrap();
}
write_view(&path, "other-sheet", 0, 2, 3, &colors[0].repeat(6)).unwrap();
let saved = combine_character_sheet(path.clone(), "sheet-test".into()).unwrap();
- assert_eq!((saved.width, saved.height), (8, 3));
+ assert_eq!((saved.width, saved.height), (43, 16));
let image = image::open(folder.path().join(&saved.relative_path))
.unwrap()
.to_rgba8();
- for (index, color) in colors.iter().enumerate() {
- assert_eq!(image.get_pixel(index as u32 * 2, 1).0, *color);
+ for ((start, end), color) in [(0, 15), (16, 24), (25, 33), (34, 42)]
+ .iter()
+ .zip(colors.iter())
+ {
+ assert_eq!(image.get_pixel(*start, 0).0, *color);
+ assert_eq!(image.get_pixel(*end, 15).0, *color);
}
discard_character_sheet_views(path.clone(), "sheet-test".into()).unwrap();
assert!(!folder
@@ -161,7 +182,7 @@ mod tests {
write_view(&path, "sheet", 0, 1, 1, &[0; 4]).unwrap();
assert!(combine_character_sheet(path.clone(), "sheet".into()).is_err());
for index in 1..4 {
- write_view(&path, "sheet", index, 2, 1, &[0; 8]).unwrap();
+ write_view(&path, "sheet", index, 2, 2, &[0; 16]).unwrap();
}
assert!(combine_character_sheet(path, "sheet".into()).is_err());
assert!(!folder.path().join("media/generated/sheet.png").exists());
diff --git a/src/lib/characterSheet.test.ts b/src/lib/characterSheet.test.ts
index 1ee5f47..f853616 100644
--- a/src/lib/characterSheet.test.ts
+++ b/src/lib/characterSheet.test.ts
@@ -8,6 +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 { characterSheetDimensions } from "./characterSheet";
vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
@@ -16,12 +17,12 @@ vi.mock("./runtime", () => ({ cancelSlopfabGeneration: vi.fn(), enqueueSlopfabGe
const handlers = new Map<string, (event: { payload: unknown }) => void>();
let stop: (() => void) | undefined;
const template: GeneratorTemplate = { id: "h3", name: "H3", modelType: "minimax-h3", defaultSteps: 20, attention: "sage2", paths: { ...EMPTY_ENGINE_SETTINGS, transformer: "C:/h3.safetensors" } };
-const result = { relativePath: "media/generated/sheet.png", width: 3072, height: 960 };
+const result = { relativePath: "media/generated/sheet.png", width: 2752, height: 1024 };
beforeEach(() => {
localStorage.clear(); vi.resetAllMocks(); handlers.clear();
Object.assign(window, { __TAURI_INTERNALS__: {} });
vi.mocked(listen).mockImplementation((async (name: string, handler: (event: { payload: unknown }) => void) => { handlers.set(name, handler); return () => {}; }) as typeof listen);
- vi.mocked(resolveSlopfabPlan).mockResolvedValue({ alignedFrames: 1, canvasWidth: 768, canvasHeight: 960 } as Awaited<ReturnType<typeof resolveSlopfabPlan>>);
+ vi.mocked(resolveSlopfabPlan).mockImplementation(async (request) => ({ alignedFrames: 1, canvasWidth: request.canvasWidth, canvasHeight: request.canvasHeight } as Awaited<ReturnType<typeof resolveSlopfabPlan>>));
vi.mocked(enqueueSlopfabGeneration).mockResolvedValue(undefined);
vi.mocked(cancelSlopfabGeneration).mockResolvedValue(true);
vi.mocked(releaseRendered).mockResolvedValue(true);
@@ -44,7 +45,7 @@ async function requestAt(index: number) {
return vi.mocked(enqueueSlopfabGeneration).mock.calls[index][0];
}
-it.each([false, true])("generates four source-conditioned views and adds only the combined sheet (source changed: %s)", async (changed) => {
+it.each([false, true])("uses a shared front-view outfit with square portrait and tall body views (source changed: %s)", async (changed) => {
const { queue, session } = setup();
const original = structuredClone(session.getSnapshot().config);
queue.enqueueCharacterSheet(session, template, "source");
@@ -52,12 +53,22 @@ it.each([false, true])("generates four source-conditioned views and adds only th
expect(queue.getSnapshot()).toHaveLength(1);
const id = queue.getSnapshot()[0].id;
let seed: number | undefined;
+ const order = [1, 0, 2, 3];
for (let index = 0; index < 4; index++) {
const request = await requestAt(index);
seed ??= request.seed;
- expect(request).toMatchObject({ stillImage: true, frames: 1, referencePaths: ["C:/Character/media/hero.png"], seed });
+ const viewIndex = order[index];
+ const referencePaths = ["C:/Character/media/hero.png", ...(index > 0 ? [`C:/Character/cache/character-sheets/${id}/1.png`] : [])];
+ expect(request).toMatchObject({ stillImage: true, frames: 1, referencePaths, seed });
+ expect(request.canvasWidth / request.canvasHeight).toBe(viewIndex === 0 ? 1 : 9 / 16);
+ expect(request.canvasHeight).toBe(1024);
+ if (index > 0) {
+ expect(invoke).toHaveBeenCalledWith("save_character_sheet_view", { folderPath: "C:/Character", sheetId: id, jobId: `${id}-view-2`, index: 1 });
+ expect(request.prompt).toContain("<Picture 2> is the full body front view of this same character and the fixed wardrobe reference");
+ expect(request.prompt).toContain("Do not add, remove, replace, restyle or recolor any clothing");
+ }
expect(request.imageEdit).toBeUndefined();
- expect(request.prompt).toContain(["frontal close-up portrait", "full body front view", "full body side view", "full body back view"][index]);
+ expect(request.prompt).toContain(["frontal close-up portrait", "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).not.toContain("A still photograph");
@@ -66,7 +77,7 @@ it.each([false, true])("generates four source-conditioned views and adds only th
emit("framesReady", request.jobId);
if (index < 3) {
await waitFor(() => expect(releaseRendered).toHaveBeenCalledWith(request.jobId));
- expect(invoke).toHaveBeenCalledWith("save_character_sheet_view", { folderPath: "C:/Character", sheetId: id, jobId: request.jobId, index });
+ expect(invoke).toHaveBeenCalledWith("save_character_sheet_view", { folderPath: "C:/Character", sheetId: id, jobId: request.jobId, index: viewIndex });
}
}
await waitFor(() => expect(queue.getSnapshot()[0].status).toBe("completed"));
@@ -81,6 +92,14 @@ it.each([false, true])("generates four source-conditioned views and adds only th
await waitFor(() => expect(invoke).toHaveBeenCalledWith("discard_character_sheet_views", { folderPath: "C:/Character", sheetId: id }));
});
+it.each(["416p", "768p", "1080p", "2048p", "4k"] as const)("keeps exact aspect ratios and aligned dimensions at %s", (resolution) => {
+ const sizes = characterSheetDimensions(resolution);
+ expect(sizes.map(({ width, height }) => width / height)).toEqual([1, 9 / 16, 9 / 16, 9 / 16]);
+ expect(new Set(sizes.map(({ height }) => height)).size).toBe(1);
+ expect(sizes.reduce((sum, { width }) => sum + width, 0)).toBeLessThanOrEqual(8192);
+ for (const { width, height } of sizes) { expect(width % 32).toBe(0); expect(height % 32).toBe(0); }
+});
+
it.each(["cancelled", "failed"])("discards partial views after the second render is %s", async (state) => {
const { queue, session } = setup();
queue.enqueueCharacterSheet(session, template, "source");
diff --git a/src/lib/characterSheet.ts b/src/lib/characterSheet.ts
index 5340798..6a89d80 100644
--- a/src/lib/characterSheet.ts
+++ b/src/lib/characterSheet.ts
@@ -1,5 +1,6 @@
import { createImageScene } from "./imageScene";
import { compileImagePrompt } from "./imagePrompt";
+import { outputDimensions } from "./export";
import type { ProjectAsset, ProjectConfig, ProjectReference } from "./project";
export const CHARACTER_SHEET_VIEWS = [
@@ -9,18 +10,32 @@ export const CHARACTER_SHEET_VIEWS = [
{ 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." },
] as const;
-export function characterSheetPrompts(config: ProjectConfig, source: ProjectAsset): string[] {
+// Establish the complete outfit before asking for any other camera angle.
+export const CHARACTER_SHEET_ORDER = [1, 0, 2, 3] as const;
+
+export function characterSheetDimensions(resolution: ProjectConfig["settings"]["resolution"]) {
+ // A shared height divisible by 512 makes both 1:1 and 9:16 exact on H3's
+ // 32px grid, and keeps the combined image below the editor's 8192px limit.
+ const height = Math.max(512, Math.min(2048, Math.round(outputDimensions(resolution, "1:1").height / 512) * 512));
+ return CHARACTER_SHEET_VIEWS.map((_, index) => ({ width: index === 0 ? height : height * 9 / 16, height }));
+}
+
+export function characterSheetPrompts(config: ProjectConfig, source: ProjectAsset, frontRelativePath: string): string[] {
const reference: ProjectReference = {
id: "character-sheet-source", 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, clothing, footwear, accessories, materials and colors. Preserve the source's visual medium and rendering style. Do not redesign or change the outfit.",
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) => {
- const scene = createImageScene(`Create a character reference view of @[ref:${reference.id}]. ${view.description} Keep the same clothing, appearance and every identifying detail from the source image. Use a plain light gray background, soft even studio lighting, and no text, labels, borders, additional characters or multiple views. Match the source image's visual style.`);
+ return CHARACTER_SHEET_VIEWS.map((view, index) => {
+ const wardrobe = index === 1
+ ? "Copy every visible garment 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 close-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 }] };
+ const scene = createImageScene(`Create a character reference view of @[ref:${reference.id}]. ${view.description} ${wardrobe} Keep the same clothing, appearance and every identifying detail from the source image. Use a plain light gray background, soft even studio lighting, and no text, labels, borders, additional characters or multiple views. Match the source image's visual style.`);
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: [reference],
+ ...config, settings: { ...config.settings, defaultLook: null }, references: [selectedReference],
imageScene: scene,
}).prompt;
});
diff --git a/src/lib/workQueue.ts b/src/lib/workQueue.ts
index e0072f5..05e0bc9 100644
--- a/src/lib/workQueue.ts
+++ b/src/lib/workQueue.ts
@@ -3,7 +3,7 @@ import { invoke } from "@tauri-apps/api/core";
import { createImageEditScene, createImageScene, imageScenePrompt } from "./imageScene";
import { compileImageEdits, imageEditDebugPrompt } from "./imageEditing";
import { compileImagePrompt } from "./imagePrompt";
-import { CHARACTER_SHEET_VIEWS, characterSheetPrompts } from "./characterSheet";
+import { CHARACTER_SHEET_ORDER, CHARACTER_SHEET_VIEWS, characterSheetDimensions, characterSheetPrompts } from "./characterSheet";
import { completeImageDraft, imageFamilyRoot, imageGenerationSnapshot, saveImageDraft } from "./imageHistory";
import type { ImageGenerationSnapshot } from "./project";
import { outputDimensions } from "./export";
@@ -58,7 +58,7 @@ export interface WorkItem {
}
interface PendingWork {
characterSheet?: {
- prompts: string[]; sourceId: string; name: string; index: number;
+ prompts: string[]; sourceId: string; name: string; index: number; frontRelativePath: string;
ready?: { resolve: () => void; reject: (reason: Error) => void };
};
outputFrames?: number;
@@ -272,19 +272,17 @@ export class WorkQueue {
if (this.items.some((item) => item.projectKey === projectKey && item.kind === "image" && item.imageAssetId === sourceId && isWorkActive(item))) return;
const config = structuredClone({ ...current, providerSettings: { ...current.providerSettings,
slopfab: engineProviderSetting(template.paths, current.providerSettings.slopfab, template.attention, template.loras, "prompt", template.additionalSafetensors, false, template.sources) } });
- const prompts = characterSheetPrompts(config, source);
- // Portrait panels leave room for head-to-toe views. Bound each panel so
- // the four-column PNG remains within the image editor's 8192px limit.
- const size = outputDimensions(config.settings.resolution, "4:5");
- const width = Math.min(2048, size.width);
- const height = Math.round(width * size.height / size.width);
const id = `character-sheet-${crypto.randomUUID()}`;
+ const frontRelativePath = `cache/character-sheets/${id}/1.png`;
+ const prompts = characterSheetPrompts(config, source, frontRelativePath);
+ const firstView = CHARACTER_SHEET_ORDER[0];
+ const { width, height } = characterSheetDimensions(config.settings.resolution)[firstView];
let finish!: () => void;
const done = new Promise<void>((resolve) => { finish = resolve; });
- const request: SlopfabGenerationRequest = { jobId: `${id}-view-1`, stillImage: true, frames: 1, prompt: prompts[0],
+ const request: SlopfabGenerationRequest = { jobId: `${id}-view-${firstView + 1}`, stillImage: true, frames: 1, prompt: prompts[firstView],
canvasWidth: width, canvasHeight: height, steps: generationStepsWithLoras(current.imageScene?.steps ?? template.defaultSteps, config),
seed: imageGenerationSeed(current.imageScene?.seed ?? -1), referencePaths: [projectItemPath(session.record.folderPath, source)!] };
- this.work.set(id, { id, image: true, characterSheet: { prompts, sourceId, name: `Character sheet - ${source.name}`, index: 0 },
+ this.work.set(id, { id, image: true, characterSheet: { prompts, sourceId, name: `Character sheet - ${source.name}`, index: 0, frontRelativePath },
imageGeneration: { ...imageGenerationSnapshot(config, prompts.join("\n\n"), template.id), usedSeed: request.seed },
session, sceneId: current.imageScene?.nodes[0].id ?? "image-root", config, snapshot: JSON.stringify(current.imageScene),
request, submitted: false, cancelled: false, done, finish });
@@ -462,7 +460,7 @@ export class WorkQueue {
const sheet = work.characterSheet;
const fraction = event.totalSteps > 0 ? Math.max(0, Math.min(1, event.step / event.totalSteps)) : 0;
this.patch(work.id, { progress: Math.max(item.progress, (sheet.index + fraction) / 4 * 0.9),
- detail: item.cancelling ? "Cancelling generation" : `Character sheet ${sheet.index + 1}/4 · ${CHARACTER_SHEET_VIEWS[sheet.index].label}` });
+ detail: item.cancelling ? "Cancelling generation" : `Character sheet ${sheet.index + 1}/4 · ${CHARACTER_SHEET_VIEWS[CHARACTER_SHEET_ORDER[sheet.index]].label}` });
return;
}
const progress = Math.max(item.progress, event.totalSteps > 0 ? Math.min(0.88, 0.12 + Math.max(0, event.step) / event.totalSteps * 0.76) : event.stage === "delivering" ? 0.88 : 0.08);
@@ -499,19 +497,25 @@ export class WorkQueue {
private async generateCharacterSheet(work: PendingWork) {
const sheet = work.characterSheet!;
const folderPath = work.session.record.folderPath;
+ const sourcePath = work.request.referencePaths[0];
+ const dimensions = characterSheetDimensions(work.config.settings.resolution);
try {
for (let index = 0; index < sheet.prompts.length; index++) {
if (work.cancelled) return;
sheet.index = index;
+ const viewIndex = CHARACTER_SHEET_ORDER[index];
+ const { width, height } = dimensions[viewIndex];
work.submitted = false;
- work.request = { ...work.request, jobId: `${work.id}-view-${index + 1}`, prompt: sheet.prompts[index] };
+ work.request = { ...work.request, jobId: `${work.id}-view-${viewIndex + 1}`, prompt: sheet.prompts[viewIndex],
+ canvasWidth: width, canvasHeight: height,
+ referencePaths: [sourcePath, ...(index > 0 ? [projectItemPath(folderPath, { relativePath: sheet.frontRelativePath })!] : [])] };
this.patch(work.id, { status: "preparing", detail: `Preparing character sheet view ${index + 1}/4` });
await resolveSlopfabPlan(work.request, work.config, folderPath);
if (work.cancelled) return;
const ready = new Promise<void>((resolve, reject) => { sheet.ready = { resolve, reject }; });
// Events can arrive before native submission returns.
void ready.catch(() => undefined);
- this.patch(work.id, { status: "generating", detail: `Character sheet ${index + 1}/4 · ${CHARACTER_SHEET_VIEWS[index].label}` });
+ this.patch(work.id, { status: "generating", detail: `Character sheet ${index + 1}/4 · ${CHARACTER_SHEET_VIEWS[viewIndex].label}` });
await enqueueSlopfabGeneration(work.request, work.config, folderPath);
work.submitted = true;
if (work.cancelled) await this.requestNativeCancellation(work);
@@ -519,7 +523,7 @@ export class WorkQueue {
sheet.ready = undefined;
if (work.cancelled) { this.cancelled(work); return; }
this.patch(work.id, { status: "encoding", detail: `Saving character sheet view ${index + 1}/4` });
- await invoke("save_character_sheet_view", { folderPath, sheetId: work.id, jobId: work.request.jobId, index });
+ await invoke("save_character_sheet_view", { folderPath, sheetId: work.id, jobId: work.request.jobId, index: viewIndex });
await releaseRendered(work.request.jobId);
}
this.patch(work.id, { status: "encoding", progress: 0.95, detail: "Combining character sheet", completionAt: null });