Skip to content

TrailView: fixed models as files, a model budget, and a workflow for better models #3782

Open
1 of 6 issues completed

Description

@timohueser

Status: approved

TL;DR

Goal: TrailView downloads every model that has one fixed shape (trees, plants, rocks, animals, benches and the other small objects) as a file that the web build makes. The device builds no model. A written contract says what any model file must keep. A workflow to make better models of every kind follows, first used for the animals.

Problem: The device builds these models at the first open and after each change of the model code: 3 tree workers, 1 plant worker and the main thread. This takes CPU time at the first open, when the ground, stamp and plan workers also need the CPU, and it holds worker memory on the phone (#3656). The device can only run cheap model code, because it has a time limit. So there is no place for detailed sources, a build-time reduction, baked light or hand-made models. The owner finds many models rough, and the animals most of all.

Decision: A step of the web build runs today's generators and today's mesh code (simplifier, lit(), colour matrices, quantize, the shape values that instances.ts derives) and writes the results as files beside the bundle. The engine fetches the files of the regions in reach and gives the meshes to the instances. In step 1 no pixel changes. A new spec, specs/trailview-models.md, holds the file format and the model budget. Step 2 is a workflow to make models ourselves in code with one shared kit, a style guide and a review page, first used for the animals: a look change with a gallery that the owner approves.

Rejected:

  • Files as today's device cache entries (float32 arrays): 2.5 to 2.8 times the bytes, and float32 changes the vertices of 6 flat models.
  • Files from the data release on R2 (obc data): a model change in engine code would need a data bake, and R2 bills each request.
  • Generated files in git: large binary changes in each model edit, and the files can differ from the code.
  • Impostor pictures as files: about 700 KB raw per model and phase against about 23 KB for all mesh tiers of a tree.
  • One file per region, or one file for all models: a region file repeats the species that regions share; one file of all trees is 3.4 MB.
  • Keep the generators on the device and add files only for hand-made models: two model paths, which is more code than one.
  • Models from asset packs (even CC0) or from image-to-3-D tools: their style differs from ours and from each other; the owner wants one style for all models. Packs are only inspiration.

Systems: trailview, web-planner (builder/web/vite.config.ts adds the build step)
Contracts: new specs/trailview-models.md
Size: M (2 systems, a new contract, more than 500 changed lines). An epic of 2 sub-issues, because the owner keeps the two steps apart.

Facts

All numbers come from this checkout (develop at f2656c2), on the M1 Pro, on 2026-11-21. The machine was busy (load average 11 on 8 cores), so the times are high.

Which models have one fixed shape

Model Built where today Shape Count
Trees: 65 species files in models/trees/ 3 workers (vegetation/model-worker.ts), kept in Cache Storage fixed per species and season phase 65 summer crowns, 69 crowns of their own phase (37 winter, 19 spring, 13 autumn), 3 tiers each
Ground plants and shrub plants: 39 files in models/plants/ 1 worker (vegetation/plant-worker.ts), not kept fixed per plant, season and seed (3 seeds) 1 tier
Rocks (3 slabs, 3 boulders) main thread, dressing/dressing.ts fixed 1 tier
Animals: 7 breeds, 19 coats (models/animals.ts) main thread, dressing.ts fixed per breed and coat 1 tier
Small objects of the kinds: bench, picnic table, firepit, barbecue, bike repair, drinking water, guidepost, shelter, shrine, 3 crosses, street lamp, culvert mouth, 4 crags main thread, structures/kind-points.ts fixed 1 tier
Pylons, stations and carriers of lifts (models/aerialways.ts) stamp worker, merged into the mesh of each map tile fixed per lift class and colour seed not instances
Ruins and lighthouses (models/landmarks.ts) stamp worker per object (footprint) not instances
Houses, bridges, tunnel parts, walls, hedges, paths workers per object not instances

Only the first five rows are instance models (models that instances/instances.ts draws many times). The lift parts are fixed shapes too, but they are merged into the tile meshes, so a file would remove no work. They stay generated, with the per-object models.

The engine today

  • A mesh vertex is 16 bytes (quantize): position as 3 × snorm16 over the model's extent and the trunk top as int16; normal as 3 × snorm8 and a "rises at dusk" byte; colour as 3 × sRGB unorm8 and 1 − glow. Indices are uint32. The pools are fixed: 6 Mi vertices (96 MiB), 6 Mi indices (24 MiB), 256 models, at most 3 mesh tiers and 1 impostor tier per model.
  • Besides quantize, instances.ts derives values from the float positions of each mesh: the extent, the radius, the spread, the shadow proxy, the impostor outlines and the sink table of a tree. These values go into the model records on the GPU.
  • Tree tiers 1 and 2 are meshoptimizer simplifications of tier 0 (crown caps of 600 and 200 triangles), with the crown colours scaled by lit(), a small software render (models/simplify.ts). A season phase draws the summer crown through a 3 × 3 colour matrix when that is within 8 sRGB steps, else a crown of its own.
  • vegetation/tree-models.ts keeps the built trees in the device cache trees (cap 24 MiB, terrain/device-cache.ts) under TREE_VERSION, the hash of the bundled worker (vite/bundle-version.ts).
  • Past the last mesh tier, a tree or a shrub draws an impostor (a flat picture). The GPU bakes it on demand into an atlas layer: 256 × 256 texels, 8 × 8 views, colour and normal, 6 mip levels, about 700 KB per model.
  • The engine imports no three.js: models/shape.ts has its own vector class, and builder/web/package.json has no three.
  • The bundled code: model-worker 196 KB (70 KB gzip, with the simplifier), plant-worker 70 KB (25 KB gzip). The tree and plant files are also in the main bundle, because forest.ts, rows.ts and plants.ts read their metadata: 21 KB and 27 KB gzip.
  • The kinds compute their placement sizes (height, half depth) from their generators at module load, also in the stamp worker and in the stamp bake. If these sizes changed, the stamp version would change, and the stamps would bake again.

Measured: one region (Alps)

The Alps pack with its base draws 17 tree models, 3 shrub plants, 5 ground plants × 3 seeds, 4 breeds (10 coats), 6 rocks and 18 small objects. Counts per model and tier; "file" is the packed 16-byte vertices with meshopt coding and then gzip.

Models Tier Count Triangles (mean) Vertices (mean) File, sum
Tree, summer crown 0 / 1 / 2 17 3,228 / 656 / 224 1,762 / 361 / 142 274 / 81 / 33 KB
Tree, crowns of their own (all phases) 0 / 1 / 2 24 2,154 / 490 / 168 1,815 / 510 / 250 337 / 109 / 53 KB
Plants, one season 0 18 113 to 155 281 to 347 51 to 63 KB
Animals 0 10 214 642 27 KB
Rocks 0 6 80 240 11 KB
Small objects 0 18 70 (24 to 141) 210 16 KB
  • Bytes of one view: about 0.5 MB in summer (trees 388 KB, plants 63 KB, animals, rocks and objects 54 KB), up to about 0.8 MB in a phase with crowns of their own. All phases of the region: 1.17 MB. All 65 tree species in all phases: 3.2 MB.
  • Other packings of the same Alps models: today's float32 arrays 6.5 MB raw; packed vertices with uint16 indices 3.0 MB raw; meshopt coding 1.5 MB; plain gzip of the packed form 1.8 MB; float32 arrays with meshopt and gzip 3.1 MB.
  • All 65 species, tree tier 0: 1,992 to 4,632 triangles (median 3,252), 1,032 to 8,754 vertices (median 1,662; the canary palm has 8,754). Tier 1: 600 to 888 triangles. Tier 2: 200 to 224 triangles. A species with all its phases: 17 to 110 KB, median 41 KB.
  • The vertices of one region in all phases: 135,000 (2.1 MiB of the 96 MiB vertex pool). All species and phases: 383,000.

Measured: the first-open time today

  • In the browser (the real workers on the Vite dev server, 3 runs): the 3 tree workers build the 17 summer crowns in 0.29 to 0.55 s (the first run includes the dev server's transform). The 14 winter crowns overlap and end 6 ms after the summer crowns. The plant worker takes 0.05 to 0.12 s for one season.
  • In Node, one thread: trees 0.66 s of CPU (summer crowns 0.47 s, the slowest species 66 ms), plants 11 to 14 ms per season, rocks, animals and small objects 18 ms on the main thread.
  • A repeat open reads the trees from the device cache; the plants build again in each session.
  • The phone was not measured. The workers run at the same time as the ground, stamp and plan workers, so the phone's first open loses this CPU time when it is most needed.

Measured: the identity of the files

  • quantize gives the same bytes when it packs positions that came from packed vertices: 0 differences in 184 meshes of the Alps. So the packed vertices in a file are the GPU's bytes.
  • Float32 storage changes the packed bytes of 6 flat models (2 rocks, 4 small objects), because their generators work in float64. So the file holds packed vertices, not float arrays.
  • The workers round the tree and plant meshes to float32 (Float32Array.from in model-worker.ts and plant-worker.ts) before quantize and the derived values; the rocks, animals and small objects reach instances.ts as float64. The build keeps the same precision for each source.
  • The derived values (radius, spread, proxy, outlines, sinks) differ in the low bits when they come from unpacked positions. So the build computes them from the same floats as the device does today (float32 for trees and plants, float64 for the others), and the file holds them.

Part 1: the model files (no pixel changes)

The build step. A Vite plugin, vite/model-files.ts, builds an entry models/bake.ts for Node, as vite/bundle-version.ts does, and runs it. The entry calls today's generators and today's mesh code and returns the files. The plugin emits each file with a content hash in its name, and gives the engine a virtual module virtual:models, the manifest. The dev server makes the files at start and again when a module of the bundled entry changes: the plugin keeps the module list of its build, as bundle-version.ts does, so a change in rules/regions.ts, vegetation/phenology.ts, structures/mesh.ts or a kind also makes new files. Because the build runs the same functions on the same inputs and at the same float precision, the output is the same by construction.

The files. One file per load that the engine asks for today:

File Holds Today's job
tree/<model>/summer 3 tiers of the summer crown a summer job of the tree workers
tree/<model>/<phase> 3 tiers of a crown of its own a crown job
plant/<model>/<season> seeds 1 to 3 a plant job
animal/<breed> 1 model per coat dressing.ts
objects the 6 rocks and the small objects of the kinds dressing.ts, kind-points.ts

A file has a short header (a magic number and a format version), then per model: the tier count, per tier the vertex count, the index count and the trunk vertex count, the crown base, and the derived values (largest coordinate, radius, spread, the sink table, the impostor outlines, the shadow proxy). Then per tier the vertex buffer (16 bytes a vertex, meshopt vertex coding) and the index buffer (meshopt index coding). The manifest holds what the engine needs before a fetch: the URL of each file; the ids of the tree and plant models (the checks model in TREES and model in PLANTS); per tree model keepsHeading (rows.ts), the colour matrix of each phase and whether the phase has a crown of its own; the plants' ground rules and sized; each breed's height and coat count. The models of the objects file are in the order of POINT_MODELS, after the rocks. The exact bytes go into specs/trailview-models.md.

The load. TreeModels and Plants keep their order (summer crowns first, the near regions first, the most trees about the eye first) and fetch a file in place of a worker job. Dressing and KindPoints fetch the animal files of the regions' herds and the objects file at start (about 60 KB) and replace their empty models when the files arrive, as the trees do today. The meshopt decoder (7.7 KB gzip) decodes a file in a few milliseconds. Instances takes the packed meshes and the derived values, and writes the bytes to the pools as they are.

Hosting and caching. The files lie beside the bundle on the site host (GitHub Pages today) and in the iOS app's copy of the bundle. Each file has a new name for each new content. Pages serves every file with max-age=600 and no immutable, so the HTTP cache alone asks the server again after 10 minutes and fails with no network. So the engine keeps the files in the device cache under one entry models, keyed by the file name, with a cap of 8 MiB (one region in all phases is 1.2 MB, all trees 3.2 MB). This replaces the trees entry and its 24 MiB cap, and needs no version key: a new content is a new name. A model change reaches a device with the next site deploy, and the device fetches only the files whose name changed. Pages deletes old files at each deploy, so a page that was open during a deploy can get a 404 for a model file, as it can for a lazy code chunk today. The engine then does not ask again in that session: the model draws nothing, and the engine warns once. Today's retry of a failed job (failed and ask in tree-models.ts) goes.

What leaves the runtime: the tree and plant workers (model-worker.ts, plant-worker.ts, model-entry.ts); the simplifier and lit() (they run only in the build); tone.ts on the device; the device cache entry trees; the tree entry of bundle-version.ts; the derived values in instances.ts (they move to models/pack.ts, which the build uses; quantize moves there too, and instances.ts still calls it for its impostor quad); the tree, plant and animal generators in the main bundle (about 50 KB gzip). The rock generator stays, because kinds/arete.ts and kinds/wall.ts import it, and the kinds keep their other generator imports for their placement sizes, because a change there bakes the stamps again. three.js is not in the engine today.

Impostors stay baked on the GPU. A file would be about 700 KB raw per model and phase, 30 times the mesh file, and the bake costs only GPU time once per model.

The proof. A test decodes each file and checks it against a fresh pack of the generator output: same vertex and index bytes, same derived values, bit for bit. In the pull request, a one-time run compares the meshes and model records that develop puts into the pools with those of the branch, for every model in every phase, season and seed, and a pixel diff of three still views (forest in summer, forest in winter, a pasture with herds) shows 0 changed pixels.

What the change gives, and costs. It removes about 0.3 to 0.55 s of worker time from the first open on the M1 Pro (the phone is not measured), 4 workers and their memory (3 × 3 + 1 MiB on the M1 Pro, #3656), 16 MiB of device cache cap (24 MiB for trees becomes 8 MiB for all models), and about 95 KB gzip of worker code and about 50 KB gzip of generator code. It adds about 0.5 to 0.8 MB of downloads per region at the first open, then the HTTP cache serves them. A box-kit session downloads about 95 MB (#2819), so this is under 1 %. On a slow phone network, 0.5 MB can take as long as the worker time that it saves; the gain then is free CPU during the load, not an earlier picture. The larger gain is the seam: models that the device could not afford to build.

Part 2: the model contract

specs/trailview-models.md is the contract for every model file, from a generator or from a hand-made asset. The build checks it and fails on a model that breaks it.

The vertex format is the 16-byte vertex above, and uint32 indices in the pools. The file codes them with meshopt.

The budget per model. Each cap comes from today's maximum over all model files (65 tree species in all phases, 39 plants in all seasons and seeds, 19 coats, 6 rocks, 18 small objects), rounded up. The build checks each cap, and the mean cap over all tree species files. A model that appears in small numbers on screen gets several times today's triangles; trees and ground plants, which fill the screen, keep today's counts.

Model Tier, and where it ends Triangles, at most Vertices, at most Where the number comes from
Tree 0, 60 m for a tree 25 m tall 4,700 9,000 today's maximum: 4,632 and 8,754
Tree 0, the mean of all tree species files 3,400 today's mean of 65 species: 3,316
Tree 1, 300 m 900 1,800 today's maximum: 888 and 1,708
Tree 2, 700 m; then the impostor to 4,500 m 230 600 today's maximum: 224 and 558
Plant, each season and seed, as a ground plant or a shrub 0, 60 m; a shrub then its impostor to 500 m 350 1,000 today's maximum of all 39 plant files: 332 and 996 (prickly pear)
Rock 0, 1,000 m 100 300 today: 80 and 240
Animal 0, 150 m 1,000 3,000 about 5 times today's 214; few on screen
Animal 1, 1,500 m 250 750 today's maximum of all 19 coats, 214, rounded up
Small object 0, its reach (300 to 1,200 m) 600 1,800 about 4 times today's largest (141)

The total of one view: at most 256 instance models (the MODELS limit), at most 3 mesh tiers per model, and at most 512,000 vertices of all models in reach. Today one region in all phases uses 135,000.

Device tiers: one set of files for desktop and phone. On the phone, the tree ranges and the small objects changed the GPU time by less than the noise (#3656), so a phone set would save nothing that we can measure. A phone lowers the tier distances and the pools through the budget table of #3656. A phone set of files waits for a measured gain.

What the build may do that the device cannot, because it has no time limit:

Tool Keeps today's pixels
Run today's generators, simplifier and lit() yes: part 1
Reorder the triangles and vertices for the GPU's vertex cache (meshopt) not by construction: when two triangles have the same depth, the first one wins. Expected to be invisible; a pixel diff decides. It can save vertex time on the phone.
Build a detailed model, then reduce it to the budget no: a look change
Bake the light that does not move with the sun (ambient occlusion, sky visibility) into the vertex colours, with a ray-cast render in place of lit() no: a look change. The sun and the time of day stay live in draw.wgsl.
Bake the impostors from tier 0 in place of tier 2 no: a look change. The bake stays on the GPU; only its source tier changes.

Texture coordinates. The 16-byte vertex has no free byte. Texture coordinates as 2 × unorm16 make the vertex 20 bytes (+25 % vertex memory and fetch), and a shared detail texture adds one texture sample to each pixel of every instance draw. We do not add them now. The file has a format version, and a format change is allowed before the release, so a later texture costs one format change. If a texture ever needs only 2 bytes: the trunk top (int16) is the same for all trunk vertices of a mesh and could move to the model record.

Part 3: a workflow to make models, first used for the animals (a look change, after part 1 merges)

The owner wants one good way to make models of every kind: trees, plants, animals and the small objects. The models must look good and have few triangles. The style is low-fidelity and game-like, not photo-real. Animals must look cute and never odd. The animals come first, because they look the roughest today.

The animals today. 7 breeds (brown, dairy and Simmental cattle, highland cow, sheep, goat, horse) in 19 coats. One build makes all of them: a body of 4 octagon rings, a neck and a head, 4 legs of 4 sides, hooves, a tail and horns. Each model has 214 triangles and 642 vertices, or 202 and 606 without horns (flat faces with their own vertices), and one tier to 1,500 m. The packs name 32 herd species and draw them with these 7 models: red deer, reindeer, ibex, chamois and the Iberian pig draw as goats; the dromedary, the donkey and the Icelandic horse draw as other breeds.

How many on screen. The Alps draw 5 groups per circle of 400 m about the eye (2 + 1 + 1 + 1), in groups of 3 to 40. In the reach of 1,500 m, that is at most about 70 groups and 800 animals when all the ground is grazed, and about 135 in a view 60 degrees wide. A real view has fewer. The gallery run counts them.

The workflow. We make every model ourselves, in code, with one shared modelling kit, so that all models have one style. Asset packs and photos are only inspiration and references; no mesh of another maker ships.

  1. The kit. One set of shared building blocks for every kind: soft primitives, a body lofted along a spine from outlines, limbs with joints, leaf and needle clusters, and the painting of faces in flat colour bands. models/shape.ts and models/flat.ts hold the start of it today. The kit also holds the style rules as code: the palettes, the size of the colour bands, the smallest part that is worth triangles, and the proportions of the style.
  2. The style guide. A short page in docs/content/ with pictures: low-fidelity and game-like, cute, never odd. For animals: a slightly large head, short legs, a round body, and clear silhouettes from the side and from above. Each model follows it.
  3. A model is one TypeScript file per species, as the trees and plants are today: its outlines (a side and a top outline of about 20 points, traced from a public-domain or CC0 photo of the species, so the proportions are real), its colours, its poses or seasons, and its seeds for variety. Season states are separate models of one species, as the crowns of a phase are today; so a flower can later have a bloom model and a non-bloom model.
  4. The build makes the tiers: it builds a detailed form, reduces each tier to the budget of part 2 with the simplifier, and fails when a model breaks the budget. Part 1's checks and packing then apply unchanged.
  5. The review page shows each model in the engine's light and look: a turntable at each tier, its triangle and vertex counts against the budget, and today's model beside it. A new or changed model gets its pictures from this page for the owner's approval.

The steps.

  1. Mock-ups: a cow, a sheep and a goat in 2 or 3 style variants made with the kit (for example more or less rounded, more or less stylized proportions), at 10 m and 100 m, in the engine next to today's models. The owner chooses the style, and the style guide records it.
  2. Build the kit, the style guide, the review page and the build's budget check, and remake the animals inside the budget of part 2: tier 0 to 150 m with at most 1,000 triangles, tier 1 to 1,500 m with at most 250. One model per herd species of the packs where the species differs in shape (about 12: cattle, highland cow, sheep, goat, ibex, chamois, red deer, reindeer, horse, donkey, pig, dromedary), with 2 or 3 poses.
  3. The gallery: before and after, the same still views, near (10 to 30 m) and far (300 to 1,000 m), summer and winter, cattle, sheep, goats and one new species. The owner approves before the merge.
  4. The frame-time check: one flight on the M1 Pro and one at the phone canvas of 780 × 1688, develop against the branch, alternated. The pass: not noticeably slower than today, within the noise.
  5. Later issues remake the trees, the plants and the small objects with the same kit and style guide, one kind at a time, each with its gallery.

Out of scope: where and when the models stand. The placement of the herds (how many herds a region draws, which regions have which animals) is temporary, and so is the placement of plants. Flowers that bloom at the right time in each region need bloom models and placement rules: a later issue.

Plan

Order: the files first, then the kit with the animals as the test of the style, then the trees, the plants and shrubs, the rocks and the small objects, one kind at a time. Every generated model of one fixed shape gets this treatment: nicer, crafted shapes in one cartoon-like style, with no more triangles than today.

The phone plan of #3656 lists the model workers in its budget table. Whichever change lands second adapts those rows.

Files

Part 1:

  • builder/web/vite/model-files.ts: create: the build step and the manifest module.
  • builder/web/vite/versions.d.ts: change: declare virtual:models; remove virtual:tree-version.
  • builder/web/vite/bundle-version.ts: change: remove the tree entry.
  • builder/web/vite.config.ts: change: add the plugin.
  • builder/web/src/lib/trailview/models/bake.ts: create: runs the generators and writes the files.
  • builder/web/src/lib/trailview/models/pack.ts: create: the file codec, and quantize and the derived values moved from instances.ts.
  • builder/web/src/lib/trailview/models/pack.test.ts: create: each file decodes to a fresh pack of the generator output.
  • builder/web/src/lib/trailview/instances/instances.ts: change: take packed meshes and their derived values.
  • builder/web/src/lib/trailview/vegetation/tree-models.ts: change: fetch files; no workers, no device cache.
  • builder/web/src/lib/trailview/vegetation/tree-models.test.ts: change: fake fetches in place of fake workers.
  • builder/web/src/lib/trailview/vegetation/plants.ts, forest.ts, rows.ts: change: fetch plant files; metadata from the manifest.
  • builder/web/src/lib/trailview/dressing/dressing.ts, structures/kind-points.ts: change: fetch the animal and object files.
  • builder/web/src/lib/trailview/vegetation/model-worker.ts, model-entry.ts, plant-worker.ts: delete.
  • builder/web/src/lib/trailview/terrain/device-cache.ts, engine.ts: change: the models entry of 8 MiB replaces trees; no TREE_VERSION.
  • specs/trailview-models.md: create: the file format and the model budget.
  • docs/design/trailview.md: change: own vite/model-files.ts.

Done when

  • The web suites that obc test affected --base origin/develop selects pass, and npm run check passes in builder/web.
  • The one-time comparison in the pull request: the pools' bytes and the model records of develop and the branch are equal for every model, phase, season and seed.
  • A pixel diff of three still views shows 0 changed pixels.
  • A cold first open of the Alps, develop against the branch, alternated, 3 runs each: on the M1 Pro and once on the iPhone 13 with the app host of prototype #3765: TrailView in the iOS app's web view on the iPhone 13 #3768. Pass: the time to the near trees and the time to the first complete view are not longer on the branch than on develop; both go into the pull request.
  • An open with no network after a first open draws the trees, plants and herds from the device cache.

Owner answers (2026-11-21)

  1. The extra download of 0.5 to 0.8 MB per region is fine.
  2. The caps are fine, if models do not get noticeably slower than today. The frame-time checks test this.
  3. We make all models ourselves, so that the style is the same for every model; asset packs are only inspiration. The best quality counts: low-fidelity, game-like, cute, never odd, with few triangles. The workflow must serve every kind of model, not only the animals. Part 3 describes it.
  4. The placement of the animals and plants is temporary, so it is out of scope here.

Requirements: none

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions