Skip to main content

mesh_samples/
mesh_samples.rs

1//! Precomputes surface points and signed-distance samples for a directory of meshes.
2//!
3//! This is the other half of the offline pipeline: `vit_tokens` turns renders
4//! into image tokens, and this turns the meshes those renders came from into
5//! the point clouds the shape autoencoder trains on. Both are frozen inputs, so
6//! both are computed once and read back from bfloat16 `.safetensors` shards.
7//!
8//! ```bash
9//! cargo run --release --example mesh_samples -- \
10//!     --meshes assets/ --out samples/ --surface 8192 --queries 200000
11//! ```
12//!
13//! Each mesh contributes three tensors, named after its file stem, and a fourth
14//! when it carries vertex colours:
15//!
16//! | Name | Shape | Contents |
17//! |---|---|---|
18//! | `{stem}.surface` | `[surface, 6]` | a point on the surface and its normal |
19//! | `{stem}.queries` | `[queries, 4]` | a query point and its signed distance |
20//! | `{stem}.transform` | `[1, 4]` | the centre and scale that fit it in the cube |
21//! | `{stem}.colors` | `[surface, 3]` | the linear RGB at each surface point |
22//!
23//! The transform is what puts a generated mesh back in the source asset's
24//! frame, so it is written even though training never reads it. The colours are
25//! the colour head's targets, interpolated across the same face the surface
26//! point was drawn from, and a mesh without them trains shape only.
27//!
28//! A run over ten thousand meshes takes hours, so it resumes: a shard whose
29//! file is already there and opens cleanly is read for its names and skipped,
30//! and `index.json` is rewritten after every shard rather than at the end. A
31//! shard left half-written by a killed run does not open — `SafeTensors::open`
32//! checks the header against the file's length — so it is simply redone.
33//! Resuming assumes the same `--meshes` directory and the same `--shard`: the
34//! chunking is by position, so a directory that gained a file reshuffles which
35//! mesh lands in which shard.
36
37use rand::SeedableRng;
38use rand::rngs::StdRng;
39use rusting_brain::mesh::{Bvh, Mesh, QuerySampling};
40use rusting_brain::safetensors::{self, Dtype, SafeTensors};
41use std::collections::BTreeMap;
42use std::path::{Path, PathBuf};
43use std::time::Instant;
44
45struct Args {
46    meshes: PathBuf,
47    out: PathBuf,
48    shard: usize,
49    surface: usize,
50    queries: usize,
51    near_surface: f32,
52    jitter: f32,
53    extent: f32,
54    seed: u64,
55}
56
57fn main() -> Result<(), Box<dyn std::error::Error>> {
58    let args = parse()?;
59    std::fs::create_dir_all(&args.out)?;
60
61    let mut paths: Vec<PathBuf> = std::fs::read_dir(&args.meshes)?
62        .filter_map(|entry| entry.ok().map(|entry| entry.path()))
63        .filter(|path| {
64            path.extension().is_some_and(|extension| {
65                matches!(extension.to_ascii_lowercase().to_str(), Some("obj" | "glb"))
66            })
67        })
68        .collect();
69    paths.sort();
70    if paths.is_empty() {
71        return Err(format!("no .obj or .glb files in {}", args.meshes.display()).into());
72    }
73    println!(
74        "{} meshes, {} per shard, {} surface and {} query points each",
75        paths.len(),
76        args.shard,
77        args.surface,
78        args.queries
79    );
80
81    let sampling = QuerySampling {
82        count: args.queries,
83        near_surface: args.near_surface,
84        jitter: args.jitter,
85        extent: args.extent,
86    };
87
88    let mut index: BTreeMap<String, String> = BTreeMap::new();
89    let mut skipped = 0;
90    let mut colored = 0;
91    let started = Instant::now();
92    let shards = paths.len().div_ceil(args.shard);
93    for (number, chunk) in paths.chunks(args.shard).enumerate() {
94        let shard = format!("samples-{number:05}.safetensors");
95
96        // Already done by an earlier run: take its names and move on.
97        let done = completed(&args.out.join(&shard));
98        if !done.is_empty() {
99            for stem in &done {
100                index.insert(stem.clone(), shard.clone());
101            }
102            write_index(&args.out, &index)?;
103            println!("{shard}: {} meshes, already written", done.len());
104            continue;
105        }
106        // One shard at a time in memory. A 200K-query mesh is 3 MB here and
107        // half that on disk, so the shard size is the knob that bounds this.
108        let mut sampled: Vec<(String, [usize; 2], Vec<f32>)> = Vec::new();
109        let mut meshes = 0;
110        for path in chunk {
111            let stem = path
112                .file_stem()
113                .and_then(|stem| stem.to_str())
114                .ok_or_else(|| format!("{} has no usable name", path.display()))?
115                .to_string();
116
117            // One bad asset in a scraped dataset should not cost the whole run.
118            let mesh = match read(path) {
119                Ok(mesh) => mesh,
120                Err(error) => {
121                    eprintln!("skipping {}: {error}", path.display());
122                    skipped += 1;
123                    continue;
124                }
125            };
126            // The seed is per mesh, so a rerun of one shard reproduces exactly
127            // the samples the first run wrote.
128            let mut rng = StdRng::seed_from_u64(args.seed ^ hash(&stem));
129            let mut mesh = mesh;
130            let placement = mesh.normalize();
131            let bvh = Bvh::build(&mesh);
132
133            let (points, normals, colors) = bvh.sample_surface_colored(args.surface, &mut rng);
134            let mut surface = Vec::with_capacity(args.surface * 6);
135            for (point, normal) in points.iter().zip(&normals) {
136                surface.extend(point);
137                surface.extend(normal);
138            }
139
140            let queries = bvh.sample_queries(&sampling, &mut rng);
141            let distances = bvh.signed_distance(&queries);
142            let mut samples = Vec::with_capacity(queries.len() * 4);
143            for (query, distance) in queries.iter().zip(&distances) {
144                samples.extend(query);
145                samples.push(*distance);
146            }
147
148            index.insert(stem.clone(), shard.clone());
149            meshes += 1;
150            sampled.push((format!("{stem}.surface"), [points.len(), 6], surface));
151            // Only the meshes that carry colour get a colour tensor; the loader
152            // treats a missing one as "this mesh trains shape only".
153            if !colors.is_empty() {
154                colored += 1;
155                sampled.push((format!("{stem}.colors"), [colors.len(), 3], colors.concat()));
156            }
157            sampled.push((format!("{stem}.queries"), [queries.len(), 4], samples));
158            sampled.push((
159                format!("{stem}.transform"),
160                [1, 4],
161                vec![
162                    placement.center[0],
163                    placement.center[1],
164                    placement.center[2],
165                    placement.scale,
166                ],
167            ));
168        }
169        if sampled.is_empty() {
170            continue;
171        }
172
173        let borrowed: Vec<(&str, &[usize], &[f32])> = sampled
174            .iter()
175            .map(|(name, shape, data)| (name.as_str(), &shape[..], &data[..]))
176            .collect();
177        safetensors::write_as(
178            args.out.join(&shard),
179            &borrowed,
180            &BTreeMap::from([
181                ("source".to_string(), "mesh_samples".to_string()),
182                ("surface".to_string(), args.surface.to_string()),
183                ("queries".to_string(), args.queries.to_string()),
184            ]),
185            Dtype::Bf16,
186        )?;
187        write_index(&args.out, &index)?;
188        println!(
189            "{shard}: {meshes} meshes, {}",
190            progress(started, number + 1, shards)
191        );
192    }
193
194    write_index(&args.out, &index)?;
195    println!(
196        "wrote {} entries to index.json, {colored} with colour, skipped {skipped}",
197        index.len()
198    );
199    Ok(())
200}
201
202/// The mesh names an already-written shard holds, or nothing if it is missing,
203/// unreadable, or was cut short by a killed run.
204fn completed(path: &Path) -> Vec<String> {
205    let Ok(shard) = SafeTensors::open(path) else {
206        return Vec::new();
207    };
208    shard
209        .names()
210        .filter_map(|name| name.strip_suffix(".surface").map(str::to_string))
211        .collect()
212}
213
214/// Rewritten after every shard, so a killed run leaves an index that describes
215/// exactly the shards that are on disk.
216fn write_index(
217    out: &Path,
218    index: &BTreeMap<String, String>,
219) -> Result<(), Box<dyn std::error::Error>> {
220    std::fs::write(out.join("index.json"), serde_json::to_vec_pretty(index)?)?;
221    Ok(())
222}
223
224/// Elapsed and remaining, estimated from the shards finished so far. Shards
225/// take roughly equal time, since they hold the same number of meshes.
226fn progress(started: Instant, done: usize, total: usize) -> String {
227    let elapsed = started.elapsed().as_secs_f32();
228    let remaining = elapsed / done.max(1) as f32 * total.saturating_sub(done) as f32;
229    format!(
230        "{done}/{total} shards, {} elapsed, {} left",
231        clock(elapsed),
232        clock(remaining)
233    )
234}
235
236fn clock(seconds: f32) -> String {
237    let seconds = seconds as u64;
238    match seconds / 60 {
239        0 => format!("{seconds}s"),
240        minutes if minutes < 60 => format!("{minutes}m"),
241        minutes => format!("{}h{:02}m", minutes / 60, minutes % 60),
242    }
243}
244
245fn read(path: &std::path::Path) -> Result<Mesh, rusting_brain::NetworkError> {
246    match path.extension().and_then(|e| e.to_str()) {
247        Some("glb") => Mesh::read_glb(path),
248        _ => Mesh::read_obj(path),
249    }
250}
251
252/// FNV-1a, so a mesh's seed depends on its name and not on its position in the
253/// directory listing.
254fn hash(name: &str) -> u64 {
255    let mut hash = 0xcbf2_9ce4_8422_2325u64;
256    for byte in name.as_bytes() {
257        hash = (hash ^ u64::from(*byte)).wrapping_mul(0x1000_0000_01b3);
258    }
259    hash
260}
261
262fn parse() -> Result<Args, Box<dyn std::error::Error>> {
263    let mut args = Args {
264        meshes: PathBuf::new(),
265        out: PathBuf::from("samples"),
266        shard: 64,
267        surface: 8192,
268        queries: 200_000,
269        near_surface: 0.7,
270        jitter: 0.02,
271        extent: 1.1,
272        seed: 0,
273    };
274    let mut rest = std::env::args().skip(1);
275    while let Some(flag) = rest.next() {
276        let mut value = || rest.next().ok_or(format!("{flag} needs a value"));
277        match flag.as_str() {
278            "--meshes" => args.meshes = value()?.into(),
279            "--out" => args.out = value()?.into(),
280            "--shard" => args.shard = value()?.parse()?,
281            "--surface" => args.surface = value()?.parse()?,
282            "--queries" => args.queries = value()?.parse()?,
283            "--near-surface" => args.near_surface = value()?.parse()?,
284            "--jitter" => args.jitter = value()?.parse()?,
285            "--extent" => args.extent = value()?.parse()?,
286            "--seed" => args.seed = value()?.parse()?,
287            other => return Err(format!("unknown flag {other}").into()),
288        }
289    }
290    if args.meshes.as_os_str().is_empty() {
291        return Err("usage: --meshes <dir> [--out <dir>] [--shard n] [--surface n] [--queries n] [--near-surface f] [--jitter f] [--extent f] [--seed n]".into());
292    }
293    if args.shard == 0 {
294        return Err("--shard needs at least one mesh".into());
295    }
296    if !(0.0..=1.0).contains(&args.near_surface) {
297        return Err("--near-surface is the fraction of queries near the surface, so 0 to 1".into());
298    }
299    Ok(args)
300}