Build the market square and a camera that walks through it, and cut the flythrough offline through the rasteriser rather than off a screen capture.

This commit is contained in:
CRTkafa 2026-09-01 03:15:29 +07:00
parent 9b4ce16c59
commit d5c816320d
6 changed files with 431 additions and 2 deletions

5
.gitignore vendored
View file

@ -11,6 +11,11 @@ dist-viewer/
renders/ renders/
glb/ glb/
# The flythrough's PNG sequence and the video cut from it. 720 frames of 1080p
# is about two gigabytes, and both come back from one command.
frames/
*.mp4
*.log *.log
*.tgz *.tgz
*.tsbuildinfo *.tsbuildinfo

View file

@ -175,6 +175,53 @@ parameters a viewer actually notices, and morphing cannot interpolate them,
so before the split they were pinned for the whole beat and the tour looked so before the split they were pinned for the whole beat and the tour looked
static. static.
## The market square
The tour above shows the models one at a time. The other way to show a kit is
to build the place it is for, and let a camera walk through it.
```sh
bun scripts/flythrough.ts --plan # the layout from above
bun scripts/flythrough.ts --still 0.35 # one frame, to look at
bun scripts/flythrough.ts --seconds 24 --fps 30 # the sequence, into frames/
```
`scripts/square.ts` is the layout: 47 placements covering every model in the
kit, each one authored rather than packed. The anvil stands beside the forge,
the tankards are on the tavern table, the tools lean where somebody left them
and the mill is at the far end. Anything with an action is switched on first,
so the sails turn, the forge burns and the sign swings while the camera moves.
The camera runs on two splines, one for where it is and one for what it is
looking at, because a camera that only looks along its own path can never show
what it is passing. It comes in at standing height, crosses the square, then
climbs and pulls back so the mill has room to be seven metres tall.
Frames are drawn by the same software rasteriser as the contact sheets, which
is the point: no browser, no GPU, no compositor, no dropped frames, exactly the
resolution asked for, and the same command produces the same file next month.
It renders about 1.5 frames a second at 1080p, so the work is split by frame
range across as many processes as there are cores:
```sh
for k in $(seq 0 11); do
bun scripts/flythrough.ts --from $((k*60)) --to $((k*60+59)) --out frames &
done; wait
```
Then cut it, at a bitrate high enough to survive being re-encoded by whatever
it gets uploaded to:
```sh
ffmpeg -framerate 30 -i frames/%05d.png -f lavfi -i anullsrc=r=48000:cl=stereo \
-c:v libx264 -profile:v high -pix_fmt yuv420p \
-b:v 18M -maxrate 20M -bufsize 36M \
-c:a aac -b:a 96k -shortest -movflags +faststart square.mp4
```
The silent audio track is deliberate: several players handle an MP4 with no
audio stream at all badly.
## Publish the viewer ## Publish the viewer
```sh ```sh

150
scripts/flythrough.ts Normal file
View file

@ -0,0 +1,150 @@
/**
* A camera moving through the market square, as a PNG sequence.
*
* Rendered offline through the same software rasteriser the contact sheets use,
* rather than captured off the viewer, and the reasons are all the same reason:
* a capture is at the mercy of whatever the compositor and the display are
* doing. Here every frame is drawn at full size whatever the machine is busy
* with, no frame is dropped, no frame is half a frame, the output is exactly
* the resolution asked for, and the same command a month from now produces the
* same file. It also runs with no browser and no GPU, so it runs in CI.
*
* Usage:
* bun scripts/flythrough.ts --plan → the layout from above
* bun scripts/flythrough.ts --still 0.35 → one frame, to look at
* bun scripts/flythrough.ts --seconds 24 --fps 30 → the sequence
* bun scripts/flythrough.ts --from 300 --to 599 → one worker's share
*
* Then, with BOTH inputs before any output option or ffmpeg reads -profile:v
* as an input flag on the silent track and stops:
* ffmpeg -framerate 30 -i frames/%05d.png -f lavfi -i anullsrc=r=48000:cl=stereo \
* -c:v libx264 -profile:v high -pix_fmt yuv420p \
* -b:v 18M -maxrate 20M -bufsize 36M \
* -c:a aac -b:a 96k -shortest -movflags +faststart square.mp4
*/
import { mkdir, writeFile } from 'node:fs/promises'
import { CatmullRomCurve3, PerspectiveCamera, Vector3 } from 'three/webgpu'
import { encodePng, gather, renderFrom, toLinear } from './raster.ts'
import { buildSquare } from './square.ts'
const args = process.argv.slice(2)
const flag = (name: string): string | undefined => {
const at = args.indexOf(`--${name}`)
return at >= 0 ? args[at + 1] : undefined
}
const has = (name: string): boolean => args.includes(`--${name}`)
const width = Number(flag('width') ?? 1920)
const height = Number(flag('height') ?? 1080)
const fps = Number(flag('fps') ?? 30)
const seconds = Number(flag('seconds') ?? 24)
const fov = Number(flag('fov') ?? 46)
const outDir = flag('out') ?? 'frames'
const groundHex = flag('ground')
const ground = groundHex ? toLinear(groundHex) : undefined
/**
* Where the camera goes, and what it is looking at while it gets there.
*
* Two curves rather than one: a camera that always looks along its own path is
* a dolly, and it can only ever show what is in front of it. Aiming separately
* is what lets the move cross the square while the frame stays on the well,
* which is the only way the things standing to the SIDE of the path get seen.
*
* The eye keeps to the lane the layout leaves open, comes in at standing height
* and climbs at the end, because the mill is 7 m tall and the shot that ends on
* it has to be able to hold it.
*/
const EYE = new CatmullRomCurve3([
new Vector3(5.2, 1.75, 5.6),
new Vector3(3.3, 1.5, 4.0),
new Vector3(1.0, 1.35, 2.2),
new Vector3(-0.9, 1.5, 0.4),
new Vector3(-1.7, 2.1, -1.0),
new Vector3(-0.6, 3.4, 1.2),
new Vector3(1.8, 5.2, 6.0),
], false, 'catmullrom', 0.5)
const AIM = new CatmullRomCurve3([
new Vector3(0.6, 1.2, -0.4),
new Vector3(-1.0, 1.1, -0.6),
new Vector3(-0.6, 1.1, -1.6),
new Vector3(0.3, 1.1, -2.4),
new Vector3(-0.2, 1.6, -3.6),
new Vector3(-0.3, 2.2, -4.6),
new Vector3(-0.35, 2.4, -5.0),
], false, 'catmullrom', 0.5)
/**
* Eased, because a move that starts at speed and stops dead reads as a cut.
*
* Smoothstep on its own leaves the middle of the run faster than the ends by
* half again, which on a 24 s tour is the difference between passing the stall
* and going past it.
*/
const ease = (t: number): number => t * t * (3 - 2 * t)
function place(camera: PerspectiveCamera, t: number): void {
const at = ease(Math.min(1, Math.max(0, t)))
camera.position.copy(EYE.getPoint(at))
camera.lookAt(AIM.getPoint(at))
}
const square = buildSquare()
console.log(`square: ${square.root.children.length} models, ${square.height.toFixed(2)} m tall`)
await mkdir(outDir, { recursive: true })
const shot = { size: width, tall: height, ground, floor: 0, height: square.height }
if (has('plan')) {
// Straight down, to check the layout rather than to look at it. The up
// vector has to move: lookAt cannot resolve a camera aimed along its own up.
const camera = new PerspectiveCamera(50, width / height, 0.05, 200)
camera.up.set(0, 0, -1)
camera.position.set(0, 26, -3)
camera.lookAt(new Vector3(0.0, 0.0, -2.34))
square.update(0.6)
await writeFile(`${outDir}/_plan.png`, encodePng(renderFrom(gather(square.root), camera, shot)))
console.log(`${outDir}/_plan.png`)
square.dispose()
} else if (flag('still') !== undefined) {
const t = Number(flag('still'))
const camera = new PerspectiveCamera(fov, width / height, 0.05, 200)
place(camera, t)
// Wound on, so the flame is a flame and the sails are not at their start.
square.update(1.4 + t * seconds)
const name = `${outDir}/_still-${t.toFixed(2)}.png`
await writeFile(name, encodePng(renderFrom(gather(square.root), camera, shot)))
console.log(name)
square.dispose()
} else {
const total = Math.round(seconds * fps)
const from = Number(flag('from') ?? 0)
const to = Math.min(total - 1, Number(flag('to') ?? total - 1))
const camera = new PerspectiveCamera(fov, width / height, 0.05, 200)
const step = 1 / fps
// Wound forward to the worker's first frame rather than started there: the
// sails and the flames are integrated per step, so a worker that begins at
// frame 900 has to have taken the 900 steps before it or its sails are at an
// angle no other worker's are, and the seam shows.
square.update(1.4)
for (let i = 0; i < from; i += 1) square.update(step)
const began = Date.now()
for (let i = from; i <= to; i += 1) {
place(camera, total > 1 ? i / (total - 1) : 0)
const frame = renderFrom(gather(square.root), camera, shot)
await writeFile(`${outDir}/${String(i).padStart(5, '0')}.png`, encodePng(frame))
square.update(step)
if ((i - from) % 30 === 0) {
const done = i - from + 1
const rate = done / ((Date.now() - began) / 1000)
console.log(`${i}/${to} ${rate.toFixed(2)} fps ${((to - i) / rate / 60).toFixed(1)} min left`)
}
}
console.log(`${to - from + 1} frames → ${outDir}/`)
square.dispose()
}

View file

@ -615,6 +615,45 @@ export function renderObject(root: Object3D, options: RenderOptions): Frame {
return frame return frame
} }
/** A scene's triangles, gathered once so a moving camera does not re-walk it. */
export type Gathered = readonly Triangle[]
/** Walks a transform tree into the flat triangle list the rasteriser draws. */
export function gather(root: Object3D): Gathered {
return collect(root)
}
/**
* Draws from a camera somebody else placed.
*
* `renderObject` fits its own camera to the subject, which is what a catalogue
* picture wants and the one thing a moving camera cannot have: the framing has
* to be continuous between frames, and a fit recomputed every frame is not. It
* also takes the triangles rather than the tree, because gathering 45,000 of
* them for each of 1,800 frames is the whole cost of a flythrough.
*/
export function renderFrom(
triangles: Gathered,
camera: PerspectiveCamera,
options: {
readonly size: number
readonly tall?: number
readonly ground?: readonly number[]
/** Y the contact shadow is cast onto. A scene's is its ground plane. */
readonly floor?: number
/** Tallest thing in the scene, which is what the shadow falls off over. */
readonly height: number
},
): Frame {
const { size, tall = size, ground, floor = 0, height } = options
const frame = newFrame(size, tall, ground)
camera.updateMatrixWorld(true)
camera.updateProjectionMatrix()
contactShadow(frame, camera, triangles, floor, height)
raster(frame, camera, triangles)
return frame
}
export function renderOne(id: string, options: RenderOptions): Frame { export function renderOne(id: string, options: RenderOptions): Frame {
const entry = CATALOG[id] const entry = CATALOG[id]
if (!entry) throw new Error(`not in catalog: ${id}`) if (!entry) throw new Error(`not in catalog: ${id}`)

181
scripts/square.ts Normal file
View file

@ -0,0 +1,181 @@
/**
* The market square: the kit arranged as a place rather than as a catalogue.
*
* The whole-kit scene in `catalog.ts` packs the models onto shelves, which is
* the right picture for the question it answers: laid out in rows on one ground
* plane, a model whose scale or tone is off has nowhere to hide. It is the
* wrong picture for a camera to move through, because rows read as rows and a
* camera travelling down one is travelling down a shelf.
*
* This is the other picture. Objects stand where somebody would have put them:
* the anvil beside the forge, tankards on the tavern table, tools leaning on
* the fence they were left against, the mill behind all of it. Nothing here is
* packed or fitted; every position is authored, which is the point.
*
* Coordinates are metres. +X is right, +Z is toward the camera's entry, and the
* mill sits at the far end so that a camera coming in from +Z has something to
* arrive at. The lane between roughly x = -1.5 and x = +3 is kept clear from
* the front edge to the well, because that is where the camera goes.
*/
import { Box3, Group, Vector3 } from 'three/webgpu'
import { FACTORIES } from '@/catalog.ts'
export interface Placement {
readonly id: string
/** Footprint centre, in metres. */
readonly at: readonly [number, number]
/** Turn about the vertical, radians. */
readonly yaw?: number
/**
* Tilt about X and Z, for the things that are leaning on something.
*
* A ladder standing upright in the open reads as a prop nobody used. Leaned
* against the stall it reads as a ladder. The tilt is applied before the
* model is seated, so a leaning object still touches the ground.
*/
readonly lean?: readonly [number, number]
/** Height to seat it at. The tavern table's top is 0.68. */
readonly on?: number
readonly patch?: Record<string, number>
}
/**
* Where everything stands.
*
* Every model in the kit appears at least once, because the scene is also the
* catalogue's advertisement and a model left out of it is a model nobody sees.
* Several appear more than once for the opposite reason: one barrel is a prop,
* two barrels and a crate are a market.
*/
export const SQUARE: readonly Placement[] = [
// --- The mill and the yard behind it ------------------------------------
{ id: 'post-mill', at: [-0.38, -7.02], yaw: 0.25 },
{ id: 'log-pile', at: [-3.75, -5.93], yaw: 0.3 },
{ id: 'hay-bale', at: [3.45, -6.08], yaw: -0.2 },
{ id: 'hay-bale', at: [4.28, -5.38], yaw: 0.4 },
{ id: 'wooden-fence', at: [-6.15, -5.77] },
{ id: 'wooden-fence', at: [5.93, -5.93] },
// --- The forge, on the left ----------------------------------------------
{ id: 'forge-hearth', at: [-4.8, -2.81], yaw: 0.42 },
{ id: 'iron-anvil', at: [-3.53, -2.03], yaw: -0.5 },
{ id: 'grindstone', at: [-5.18, -1.09], yaw: 0.25 },
{ id: 'wooden-bucket', at: [-4.05, -1.17] },
{ id: 'iron-cauldron', at: [-6.0, -3.59], yaw: 0.2 },
{ id: 'round-shield', at: [-3.97, -3.59], yaw: 0.5, lean: [-0.28, 0] },
{ id: 'straw-broom', at: [-5.7, -1.87], lean: [0.16, 0.1] },
{ id: 'pitch-torch', at: [-6.0, -0.47] },
{ id: 'wooden-crate', at: [-4.43, -0.31], yaw: 0.35 },
// --- The tavern, on the right --------------------------------------------
{ id: 'tavern-sign', at: [4.72, -2.65], yaw: -0.35 },
{ id: 'trestle-table', at: [3.68, -1.09], yaw: 0.18 },
{ id: 'wooden-bench', at: [3.68, -0.35], yaw: 0.18 },
{ id: 'wooden-bench', at: [3.68, -1.83], yaw: 0.18 },
{ id: 'wooden-stool', at: [4.72, -0.78], yaw: -0.4 },
{ id: 'oak-tankard', at: [3.34, -1.17], on: 0.68 },
{ id: 'oak-tankard', at: [3.86, -0.98], on: 0.68 },
{ id: 'leather-book', at: [4.01, -1.25], on: 0.68, yaw: 0.3 },
{ id: 'glass-phial', at: [3.56, -1.29], on: 0.68 },
{ id: 'coin-pouch', at: [3.71, -0.94], on: 0.68, yaw: -0.4 },
{ id: 'iron-lantern', at: [4.16, -1.05], on: 0.68 },
{ id: 'wooden-chest', at: [5.25, -1.87], yaw: -0.3 },
{ id: 'wooden-barrel', at: [5.47, -0.7] },
// --- The square itself ---------------------------------------------------
{ id: 'stone-well', at: [0.3, -2.34], yaw: 0.15 },
{ id: 'stone-trough', at: [-1.58, -1.25], yaw: 0.55 },
{ id: 'bronze-bell', at: [1.72, -3.28], yaw: -0.25 },
// --- The stall, front left -----------------------------------------------
{ id: 'market-stall', at: [-2.55, 1.4], yaw: 0.22 },
{ id: 'vegetables', at: [-2.92, 1.99], yaw: 0.1 },
{ id: 'wicker-basket', at: [-2.03, 2.03] },
{ id: 'linen-sack', at: [-3.45, 1.87], yaw: 0.3 },
{ id: 'wooden-crate', at: [-3.97, 1.33], yaw: 0.45 },
{ id: 'wooden-barrel', at: [-1.58, 2.11] },
{ id: 'wooden-ladder', at: [-4.8, 0.94], yaw: 0.3, lean: [0.22, 0] },
// --- The cart and the tools, front right ---------------------------------
{ id: 'hand-cart', at: [2.7, 1.87], yaw: -0.4 },
{ id: 'cart-wheel', at: [4.43, 1.25], yaw: -0.6, lean: [-0.2, 0] },
{ id: 'wooden-hoe', at: [5.03, 0.31], yaw: 0.2, lean: [0.18, 0.1] },
{ id: 'wooden-shovel', at: [5.21, 0.58], yaw: 0.1, lean: [0.2, 0.06] },
{ id: 'wooden-pitchfork', at: [5.4, 0.86], yaw: -0.1, lean: [0.16, -0.08] },
{ id: 'wooden-stool', at: [1.95, 1.17], yaw: 0.5 },
{ id: 'pitch-torch', at: [1.5, 0.16] },
{ id: 'wooden-fence', at: [-6.45, 1.72], yaw: Math.PI / 2 },
{ id: 'wooden-fence', at: [6.45, 1.87], yaw: Math.PI / 2 },
]
/**
* What is switched on before the camera arrives.
*
* Every one of these is off by default, which is right for a catalogue picture
* and wrong for a place: an unlit forge is a stone box, and a mill whose sails
* are stopped is the one thing in the scene a viewer will read as broken.
*/
const WAKE: Readonly<Record<string, (actions: Record<string, (arg?: unknown) => unknown>) => void>> = {
'post-mill': (a) => { a.setTurning?.(true) },
'forge-hearth': (a) => { a.setLit?.(true) },
'iron-cauldron': (a) => { a.setLit?.(true) },
'pitch-torch': (a) => { a.setLit?.(true) },
'iron-lantern': (a) => { a.setLit?.(true) },
'grindstone': (a) => { a.crank?.() },
'tavern-sign': (a) => { a.push?.() },
}
export interface Square {
readonly root: Group
/** Called once per frame, so the sails turn and the forge burns. */
readonly update: (seconds: number) => void
readonly dispose: () => void
readonly height: number
}
/** Builds the square. Every placement is a fresh model, so repeats are cheap. */
export function buildSquare(layout: readonly Placement[] = SQUARE): Square {
const root = new Group()
root.name = 'market-square'
const built: { update?: (s: number) => void; dispose: () => void }[] = []
for (const spot of layout) {
const make = FACTORIES[spot.id]
if (!make) throw new Error(`not in catalog: ${spot.id}`)
const model = make()
if (spot.patch) model.configure(spot.patch)
const [lx, lz] = spot.lean ?? [0, 0]
model.root.rotation.set(lx, spot.yaw ?? 0, lz)
model.root.updateMatrixWorld(true)
// Seat it AFTER the turn: the box of a leaning ladder is not the box of a
// standing one, and seating on the standing box leaves it in the air.
const box = new Box3().setFromObject(model.root)
const centre = box.getCenter(new Vector3())
model.root.position.set(
spot.at[0] - centre.x,
(spot.on ?? 0) - box.min.y,
spot.at[1] - centre.z,
)
WAKE[spot.id]?.(model.actions as Record<string, (arg?: unknown) => unknown>)
root.add(model.root)
built.push(model)
}
root.updateMatrixWorld(true)
const height = new Box3().setFromObject(root).getSize(new Vector3()).y
return {
root,
height,
update: (seconds: number) => {
for (const model of built) model.update?.(seconds)
root.updateMatrixWorld(true)
},
dispose: () => {
for (const model of built) model.dispose()
},
}
}

View file

@ -135,8 +135,15 @@ interface KitModel {
const as = (make: () => unknown) => make as () => KitModel const as = (make: () => unknown) => make as () => KitModel
/** Registry name → factory. The first thing that cannot be derived from metadata. */ /**
const FACTORIES: Readonly<Record<string, () => KitModel>> = { * Registry name → factory. The first thing that cannot be derived from metadata.
*
* Exported because the viewer's own `build()` hands back what a viewer needs,
* which is one primary action and a label for its button. A scene needs the
* model's own typed actions: nothing in the viewer's shape can tell a mill to
* turn.
*/
export const FACTORIES: Readonly<Record<string, () => KitModel>> = {
'wooden-barrel': as(createBarrel), 'wooden-barrel': as(createBarrel),
'wooden-bucket': as(createBucket), 'wooden-bucket': as(createBucket),
'wooden-crate': as(createCrate), 'wooden-crate': as(createCrate),