@hraness/slopcamera 3.3.6 → 3.4.0

package/examples/style-portfolio/finish-film.ts

@@ -0,0 +1,152 @@
+/** Bounded local finishing example using Slopcamera's typed video-look compiler. */
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir, realpath, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { createVisualStyleVideoLook } from "../../apps/desktop/core/visual-style-look";
+import { compileVideoLookToFfmpeg } from "../../apps/desktop/core/video-effects";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const maxInputBytes = 512 * 1024 * 1024;
+const ProbeSchema = z.strictObject({
+  programs: z.array(z.strictObject({})).max(0).optional(),
+  stream_groups: z.array(z.strictObject({})).max(0).optional(),
+  streams: z.array(z.strictObject({
+    index: z.number().int().min(0).max(31),
+    codec_type: z.enum(["video", "audio"]),
+    width: z.number().int().min(64).max(4096).multipleOf(2).optional(),
+    height: z.number().int().min(64).max(4320).multipleOf(2).optional(),
+    avg_frame_rate: z.string().regex(/^\d{1,9}\/\d{1,9}$/u).optional(),
+    nb_read_frames: z.string().regex(/^\d{1,7}$/u).optional(),
+  })).min(1).max(2),
+  format: z.strictObject({ duration: z.string().max(32).regex(/^\d+(?:\.\d+)?$/u) }),
+});
+
+export function parseFilmProbe(value: unknown, requireFrameCount = false) {
+  const probe = ProbeSchema.parse(value);
+  const videos = probe.streams.filter(stream => stream.codec_type === "video");
+  const video = videos[0];
+  const duration = Number(probe.format.duration);
+  if (videos.length !== 1 || video?.width === undefined || video.height === undefined
+    || video.avg_frame_rate === undefined || !Number.isFinite(duration) || duration <= 0 || duration > 30) {
+    throw new Error("Use one video stream and at most one audio stream, with at most 30 seconds and even 64–4096 × 64–4320 dimensions.");
+  }
+  const [numerator, denominator] = video.avg_frame_rate.split("/").map(Number);
+  const frameRate = numerator! / denominator!;
+  const frameCount = video.nb_read_frames === undefined ? undefined : Number(video.nb_read_frames);
+  if (!Number.isFinite(frameRate) || frameRate <= 0 || frameRate > 120
+    || (frameCount !== undefined && (frameCount < 1 || frameCount > 3600))
+    || (requireFrameCount && frameCount === undefined)) {
+    throw new Error("Use a finite video rate no higher than 120 fps and at most 3600 decoded frames.");
+  }
+  return { width: video.width, height: video.height, duration, frameRate, frameCount,
+    absoluteVideoIndex: video.index, audioStreams: probe.streams.length - 1 };
+}
+
+/** FFprobe indices are absolute; the look compiler selects a video-relative stream. */
+export function createFilmFinishPlan(style: unknown, probe: unknown) {
+  const facts = parseFilmProbe(probe);
+  const look = createVisualStyleVideoLook(style, { height: facts.height, seed: 19060414 });
+  return { facts, look, compiled: compileVideoLookToFfmpeg(look, { videoStreamIndex: 0 }) };
+}
+
+async function sha256(path: string) {
+  const hash = createHash("sha256");
+  let bytes = 0;
+  for await (const chunk of createReadStream(path)) {
+    bytes += chunk.length;
+    if (bytes > maxInputBytes) throw new Error("Media exceeds the 512 MiB byte limit.");
+    hash.update(chunk);
+  }
+  return hash.digest("hex");
+}
+
+async function command(argv: string[], timeoutMs = 600_000) {
+  const child = Bun.spawn(argv, { cwd: root, stdout: "pipe", stderr: "pipe" });
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, timeoutMs);
+  async function collect(stream: ReadableStream<Uint8Array>): Promise<string> {
+    const reader = stream.getReader();
+    const chunks: Uint8Array[] = [];
+    let bytes = 0;
+    try {
+      for (;;) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        bytes += chunk.value.byteLength;
+        if (bytes > 128 * 1024) {
+          child.kill("SIGKILL");
+          await reader.cancel();
+          throw new Error(`${argv[0]} exceeded its 128 KiB output bound.`);
+        }
+        chunks.push(chunk.value);
+      }
+      return Buffer.concat(chunks).toString("utf8");
+    } finally { reader.releaseLock(); }
+  }
+  try {
+    const [code, stdout, stderr] = await Promise.all([child.exited, collect(child.stdout), collect(child.stderr)]);
+    if (timedOut) throw new Error(`${argv[0]} exceeded its ${timeoutMs} ms deadline.`);
+    if (code !== 0) throw new Error(`${argv[0]} failed (${code}): ${stderr.slice(-6000)}`);
+    return stdout;
+  } catch (error) {
+    child.kill("SIGKILL");
+    await child.exited;
+    throw error;
+  } finally { clearTimeout(timer); }
+}
+
+async function probe(path: string, countFrames = false): Promise<unknown> {
+  return JSON.parse(await command(["ffprobe", "-v", "error", "-protocol_whitelist", "file",
+    ...(countFrames ? ["-count_frames"] : []), "-show_entries",
+    "stream=index,codec_type,width,height,avg_frame_rate,nb_read_frames:format=duration", "-of", "json", path], 30_000)) as unknown;
+}
+
+export async function finishFilm(args: readonly string[], workspaceRoot = root, log: (message: string) => void = console.log): Promise<void> {
+  const [inputArg, style, outputArg, ...extra] = args;
+  if (!inputArg || !style || !outputArg || extra.length) throw new Error("Usage: bun examples/style-portfolio/finish-film.ts <input-video> <style-id> <new-output.mp4>");
+  const canonicalRoot = await realpath(workspaceRoot);
+  const input = await realpath(resolve(canonicalRoot, inputArg));
+  const output = resolve(canonicalRoot, outputArg);
+  const outputRoot = resolve(canonicalRoot, "artifacts/style-portfolio");
+  const outputRelative = relative(outputRoot, output);
+  if (isAbsolute(outputRelative) || outputRelative.startsWith("..") || !output.endsWith(".mp4")) throw new Error("Output must be a new .mp4 within artifacts/style-portfolio.");
+  // FFmpeg's existence check can follow a dangling symlink to a new target.
+  // Reject the directory entry itself before any media work; retain -n as well.
+  try {
+    await lstat(output);
+    throw new Error("Output already exists, including a symlink. Choose a new output path.");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const inputStat = await stat(input);
+  if (input === output || !inputStat.isFile() || inputStat.size < 1 || inputStat.size > maxInputBytes) throw new Error("Input must be a distinct regular file no larger than 512 MiB.");
+  const { facts, look, compiled } = createFilmFinishPlan(style, await probe(input));
+  await mkdir(dirname(output), { recursive: true });
+  if (await realpath(dirname(output)) !== dirname(output)) throw new Error("Output parents must not be symlinks.");
+  const inputSha256 = await sha256(input);
+  const intent = { kind: "slopcamera.style-finish-intent", input, inputSha256, output, style, look,
+    source: facts, compiler: compiled.compiler, compilerVersion: compiled.compilerVersion, lookHash: compiled.lookHash };
+  await writeFile(`${output}.intent.json`, JSON.stringify(intent, null, 2) + "\n", { flag: "wx" });
+  const argv = ["ffmpeg", "-hide_banner", "-loglevel", "error", "-n", "-protocol_whitelist", "file", "-i", input,
+    "-filter_complex", compiled.filterGraph, "-map", `[${compiled.outputLabel}]`, "-map", "0:a:0?",
+    "-c:v", "libx264", "-preset", "slow", "-crf", "15", "-pix_fmt", "yuv420p",
+    "-c:a", "aac", "-b:a", "320k", "-movflags", "+faststart", "-color_primaries", "bt709",
+    "-color_trc", "bt709", "-colorspace", "bt709", "-threads", "4", output];
+  await command(argv);
+  if (await sha256(input) !== inputSha256) throw new Error("Source changed during finishing; retain this output as rejected and inspect the intent.");
+  const delivered = parseFilmProbe(await probe(output, true), true);
+  if (delivered.width !== facts.width || delivered.height !== facts.height || delivered.audioStreams !== facts.audioStreams
+    || Math.abs(delivered.duration - facts.duration) > 0.15 || Math.abs(delivered.frameRate - facts.frameRate) > .05) {
+    throw new Error("Finished dimensions, audio streams, duration, or frame rate do not match source.");
+  }
+  const receipt = { ...intent, kind: "slopcamera.style-finish-receipt", outputSha256: await sha256(output), bytes: (await stat(output)).size,
+    dimensions: { width: delivered.width, height: delivered.height }, frameCount: delivered.frameCount, duration: delivered.duration,
+    limitations: ["Display-referred artistic finish, not a spectral film-stock simulation.", "Diffusion approximates highlight glow; this adapter does not apply gate weave or alter capture cadence."] };
+  await writeFile(`${output}.receipt.json`, JSON.stringify(receipt, null, 2) + "\n", { flag: "wx" });
+  log(JSON.stringify({ output, receipt: `${output}.receipt.json`, dimensions: receipt.dimensions, frameCount: receipt.frameCount }));
+}
+
+if (import.meta.main) await finishFilm(process.argv.slice(2));

package/examples/style-portfolio/market-street/README.md

@@ -0,0 +1,43 @@
+# Market Street film study
+
+This editable Blender scene depicts a short cable-car journey toward a Ferry Building interpretation. It combines procedural masonry, shopfronts, open-spoked vehicles, articulated pedestrians and horses, damp paving, and atmospheric depth in a native 4:3 composition. Slopcamera Studio retains the source bundle, execution receipt, frame sequence, and Blender scene.
+
+The scene is an authored historical interpretation. Its compressed streetscape, building dimensions, shop occupants, people, traffic, and lighting are invented. It is not original footage, a restoration, or a surveyed reconstruction. Its geometry needs visual review at the intended delivery resolution before a render can support a quality claim.
+
+## Source contract
+
+Import `source.json` as a Blender source bundle. Its entrypoint is `scene.py`, which exports `build(context)`. The only bundled Python dependencies are `mesh.py` and `street_data.py`. The source uses Blender's bundled font, creates its materials locally, and does not fetch assets or read environment variables.
+
+| Control | Default | Meaning |
+| --- | --- | --- |
+| `parameters.frames` | `6 × job frame rate` | Animation frames to author, bounded to 1–480 |
+| `parameters.seed` | `19060414` | Seed for all procedural placement and surface variation |
+| `render.frameRate` | `16/1` | Simulation and capture rate, bounded to 1–60 fps |
+| `render.width`, `render.height` | `1920`, `1440` | Native output size |
+| `render.startFrame` | `1` | Initial frame after scene construction |
+
+Use an Eevee job with 64 samples, opaque RGB PNG frames, and `AgX` view transform. The scene requests AgX Medium High Contrast, exposure `-0.10`, and gamma `1`. Rendering remains the host's responsibility. The source does not change native job admission, output paths, resource limits, or execution authority.
+
+At 16 fps, `parameters.frames: 96` authors six seconds. For a single-frame proof of the full animation, keep `frames: 96` and select one frame in the job's render interval. A full job uses `startFrame: 1` and `endFrameExclusive: 97`. A 24 fps job can use `frames: 144`; the physical speeds remain the same. Sixteen fps is an authored cadence choice. It is not a claim about the original camera's precise crank rate.
+
+The camera starts at `(-2.1, 185, 2.72)` metres, travels toward negative Y at `4.4 m/s`, and looks toward `(0, -12, 12.5)`. A 32 mm lens on a 36 mm sensor keeps the tower and street in view. This is a level traveling view with slight mechanical vibration. The one-sided blocks are compressed composition coordinates, not geographic coordinates.
+
+The scene records its evidence, interpretation limits, seed, capture rate, camera, and object counts in the Blender scene's `historical_film_study` property. When Studio supplies `workingRoot`, it also writes `creative-metadata.json` there once.
+
+## Historical evidence
+
+- The [Library of Congress film record](https://www.loc.gov/item/00694408/) describes a cable-car viewpoint moving toward the Ferry Building, identifies the source as silent black-and-white 35 mm film, and documents the mixed street traffic and puddles. The scene follows those broad visual observations. The Library's catalog associates the film with April 14, 1906; the scene uses the broader description “before the April 1906 earthquake.”
+- The [San Francisco Municipal Transportation Agency's account of the 1906 conversion](https://www.sfmta.com/blog/how-1906-earthquake-transformed-our-public-transit-system) places the installation of Market Street's electric traction infrastructure after the earthquake. This scene omits longitudinal overhead traction wires. Electric cars did cross Market at intersections in the original film; this omission does not imply that no electric transit existed in the city.
+- The [San Francisco Planning Department's Path of Gold landmark report](https://commissions.sfplanning.org/hpcpackets/2014.794A.pdf) dates the bases to 1908 and the globe tops to 1916. Those standards are omitted. The smaller street posts here are period-inspired inventions rather than identified historical fixtures.
+
+The source does not claim that a Sanborn map, OpenSFHistory photograph, or other archival object was measured unless its specific record and use are documented. No archival photograph is bundled or projected onto the scene. Named collection references in the earlier prototype were insufficient evidence for its claimed dimensions and confidence levels.
+
+## Visual foundations
+
+The street is designed to read in monochrome before film finishing. Materials use world-scale masonry joints, roughness, surface variation, and bump; glazing sits visibly inside projecting jambs and faceted projecting bays. The tower, cornices, canvas awnings, silhouettes, and traffic provide different spatial scales. Pedestrians walk and cross the road, horse legs articulate, and vehicles move independently of the camera. Static architectural detail is batched by material to keep the scene manageable.
+
+The first native proof exposed a flat tonal range, fog washing out the foreground, party-wall brick mapping collapsing into stripes, and polygon puddles reading as opaque cutouts. The revision separates visible sky brightness from ambient fill, uses more oblique sunlight, confines haze to the distant block, fixes masonry mapping on both wall orientations, and models dampness through surface roughness. Near traffic is kept far enough away for its procedural silhouettes to support the composition.
+
+Keep transfer effects restrained: subtle grain at delivery resolution, small gate weave, mild luminance variation, and occasional dirt. Preserve masonry detail and tonal separation. Scratches, a sepia wash, or blur cannot substitute for believable geometry, occlusion, light, and movement. A clean high-resolution master can retain an early-film cadence.
+
+Review the first, middle, and final frames and a moving preview for geometry intersections, frozen wheels, foot sliding, shadow artifacts, and legibility of the destination. Vehicles use eased interpolation between endpoint poses; the camera is sampled along its travel at each captured frame. Wheel spokes do not rotate independently in this example, and the figures and vehicles remain procedural approximations. Film finishing should not be used to describe those limitations as archival authenticity.

package/examples/style-portfolio/market-street/mesh.py

@@ -0,0 +1,145 @@
+"""Small deterministic mesh batches for an authored Blender scene.
+
+Static street details share a mesh per material. Moving figures and vehicles
+keep their own batches so animation never needs a scene-wide object search.
+"""
+
+import math
+
+import bpy
+from mathutils import Euler, Vector
+
+
+class Batch:
+    def __init__(self, name):
+        self.name = name
+        self.groups = {}
+
+    def mesh(self, material, vertices, faces, smooth=False):
+        group = self.groups.setdefault(material.name, [material, [], [], []])
+        offset = len(group[1])
+        group[1].extend(vertices)
+        face_list = list(faces)
+        group[2].extend(tuple(offset + i for i in face) for face in face_list)
+        group[3].extend([smooth] * len(face_list))
+
+    def box(self, material, center, size, rotation=None):
+        x, y, z = center
+        dx, dy, dz = (s / 2 for s in size)
+        points = [Vector((sx * dx, sy * dy, sz * dz))
+                  for sx in (-1, 1) for sy in (-1, 1) for sz in (-1, 1)]
+        if rotation:
+            transform = Euler(rotation).to_matrix()
+            points = [transform @ p for p in points]
+        vertices = [(x + p.x, y + p.y, z + p.z) for p in points]
+        self.mesh(material, vertices, [(0, 1, 3, 2), (4, 6, 7, 5),
+                                      (0, 4, 5, 1), (2, 3, 7, 6),
+                                      (0, 2, 6, 4), (1, 5, 7, 3)])
+
+    def cone(self, material, center, radius, height, top=None, segments=12,
+             rotation=None, smooth=False):
+        if top is None:
+            top = radius
+        matrix = Euler(rotation).to_matrix() if rotation else None
+        origin = Vector(center)
+        vertices = []
+        for z, r in ((-height / 2, radius), (height / 2, top)):
+            for index in range(segments):
+                angle = math.tau * index / segments
+                point = Vector((r * math.cos(angle), r * math.sin(angle), z))
+                vertices.append(tuple(origin + (matrix @ point if matrix else point)))
+        faces = [tuple(reversed(range(segments))), tuple(range(segments, segments * 2))]
+        faces += [(i, (i + 1) % segments, (i + 1) % segments + segments, i + segments)
+                  for i in range(segments)]
+        self.mesh(material, vertices, faces, smooth=smooth)
+
+    def ellipsoid(self, material, center, radii, segments=14, rings=8):
+        x, y, z = center
+        a, b, c = radii
+        vertices = [(x, y, z + c)]
+        for ring in range(1, rings):
+            phi = math.pi * ring / rings
+            for index in range(segments):
+                theta = math.tau * index / segments
+                vertices.append((x + a * math.sin(phi) * math.cos(theta),
+                                 y + b * math.sin(phi) * math.sin(theta),
+                                 z + c * math.cos(phi)))
+        bottom = len(vertices)
+        vertices.append((x, y, z - c))
+        faces = [(0, 1 + i, 1 + (i + 1) % segments) for i in range(segments)]
+        for ring in range(rings - 2):
+            first = 1 + ring * segments
+            next_ring = first + segments
+            faces.extend((first + i, next_ring + i, next_ring + (i + 1) % segments,
+                          first + (i + 1) % segments) for i in range(segments))
+        first = 1 + (rings - 2) * segments
+        faces.extend((first + i, bottom, first + (i + 1) % segments)
+                     for i in range(segments))
+        self.mesh(material, vertices, faces, smooth=True)
+
+    def beam(self, material, start, end, radius, segments=8):
+        delta = Vector(end) - Vector(start)
+        self.cone(material, tuple((Vector(start) + Vector(end)) / 2), radius,
+                  delta.length, segments=segments,
+                  rotation=delta.to_track_quat('Z', 'Y').to_euler(), smooth=True)
+
+    def wheel(self, material, center, radius, width=0.075, spokes=12):
+        """An open spoked wheel with its axle along X."""
+        x, y, z = center
+        vertices, faces = [], []
+        segments = 36
+        for i in range(segments):
+            theta = math.tau * i / segments
+            for dx, r in ((-width / 2, radius), (width / 2, radius),
+                          (-width / 2, radius - 0.055), (width / 2, radius - 0.055)):
+                vertices.append((x + dx, y + r * math.sin(theta), z + r * math.cos(theta)))
+        for i in range(segments):
+            a, b = i * 4, ((i + 1) % segments) * 4
+            faces.extend(((a, b, b + 1, a + 1), (a + 2, a + 3, b + 3, b + 2),
+                          (a, a + 2, b + 2, b), (a + 1, b + 1, b + 3, a + 3)))
+        self.mesh(material, vertices, faces)
+        for i in range(spokes):
+            angle = math.tau * i / spokes
+            self.beam(material, center, (x, y + (radius - .045) * math.sin(angle),
+                                         z + (radius - .045) * math.cos(angle)), .025, 6)
+        self.cone(material, center, .095, width * 2.5, segments=12,
+                  rotation=(0, math.pi / 2, 0))
+
+    def finish(self, parent=None):
+        objects = []
+        for material, vertices, faces, smooth in self.groups.values():
+            mesh = bpy.data.meshes.new(self.name + ' / ' + material.name)
+            mesh.from_pydata(vertices, [], faces)
+            mesh.update()
+            mesh.materials.append(material)
+            obj = bpy.data.objects.new(mesh.name, mesh)
+            bpy.context.collection.objects.link(obj)
+            for poly, enabled in zip(mesh.polygons, smooth):
+                poly.use_smooth = enabled
+            if parent:
+                obj.parent = parent
+            objects.append(obj)
+        return objects
+
+
+def empty(name, parent=None):
+    obj = bpy.data.objects.new(name, None)
+    bpy.context.collection.objects.link(obj)
+    obj.parent = parent
+    return obj
+
+
+def text_label(name, text, location, normal, size, material, parent=None):
+    curve = bpy.data.curves.new(name, 'FONT')
+    curve.body = text
+    curve.align_x = 'CENTER'
+    curve.size = size
+    curve.extrude = 0
+    curve.space_character = 1.06
+    obj = bpy.data.objects.new(name, curve)
+    bpy.context.collection.objects.link(obj)
+    obj.location = location
+    obj.rotation_euler = Vector(normal).to_track_quat('Z', 'Y').to_euler()
+    obj.data.materials.append(material)
+    obj.parent = parent
+    return obj