Files
texturecraft/crates/formats/README.md

162 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# texturecraft-formats
File formats for TextureCraft: mesh import and export, texture export with presets, and the
`.tcraft` project file. Every reader takes untrusted bytes and returns `Result`; nothing panics on bad
input. Byte-based functions work on every target (the web build loads and saves through bytes);
path-based functions are native only (`#[cfg(not(target_arch = "wasm32"))]`).
## Public API
### Mesh import (`mesh_import`)
```rust
pub fn import_mesh_bytes(file_name: &str, bytes: &[u8]) -> Result<ImportedMesh>;
pub fn import_mesh(path: &Path) -> Result<ImportedMesh>; // native, = read_mesh_file + import_mesh_bytes
pub fn self_contained_mesh(name: &str, bytes: Vec<u8>, read: &mut dyn FnMut(&str) -> Option<Vec<u8>>) -> Result<MeshFile>;
pub fn read_mesh_file(path: &Path) -> Result<MeshFile>; // native
pub struct MeshFile { pub name: String, pub bytes: Vec<u8>, pub warnings: Vec<String> }
pub struct ImportedMesh { pub mesh: Mesh, pub report: MeshReport }
pub struct MeshReport {
pub triangles: usize, pub vertices: usize, pub materials: usize,
pub uvs_generated: bool, pub uv_out_of_range: usize, pub overlap_ratio: f32,
pub zero_area_uv_triangles: usize, pub warnings: Vec<String>,
}
```
| Format | Notes |
|---|---|
| `.glb` / `.gltf` | Default scene's node tree flattened to world space; normals by inverse transpose; winding flipped under mirroring transforms; one submesh per material (`Default` for none, `Material_<i>` when unnamed); missing normals are flat (glTF rule). Bytes: GLB or data-URI buffers and images; `self_contained_mesh` folds a `.gltf`'s `.bin` files and images from its folder in as data URIs (files outside the folder are never read). Triangle primitives only; sparse accessors are refused. Cameras (perspective `yfov`, orthographic `ymag`) become `ImportedMesh::cameras`. |
| `.fbx` | FBX 6.x and 7.x, binary (32- and 64-bit node records, zlib arrays) and ASCII. Every `Mesh` geometry connected to a Model, with the Model hierarchy's transforms (`Lcl Translation/Rotation/Scaling`, `RotationOrder`, `Pre/PostRotation`, pivots and offsets, geometric transform); normals and UV set 0 from the layer elements (`ByPolygonVertex`, `ByControlPoint`, `ByPolygon`, `AllSame`; `Direct` / `IndexToDirect`); per-polygon materials named by the Materials connected to the Model. Units (`UnitScaleFactor`, cm by default) become meters and the axis system becomes Y up. Camera Models become cameras (looking down +X; lens from the Camera NodeAttribute or, in FBX 6, the Model: `FocalLength` over `FilmHeight`, else `FieldOfViewY` / `FieldOfView`; `CameraProjectionType` 1 orthographic); FBX 6's Producer views are skipped. Materials bring `DiffuseColor` × `DiffuseFactor` and the diffuse texture, embedded or a file: `self_contained_mesh` packages an FBX with the texture files it names (`RelativeFilename`, else the file name of `FileName`) found in its folder, a stored zip that still reads as `.fbx`. FBX 5 and older are refused; decoded data is capped at 2 GiB. |
| `.dae` | COLLADA: `triangles`, `polylist`, `polygons` (holes ignored) with `VERTEX` / `NORMAL` / `TEXCOORD` inputs at any offset (lowest `set`); materials by `bind_material` symbol; the visual scene's node tree (`matrix`, `translate`, `rotate`, `scale`, `lookat`, `instance_node`, skinned `instance_controller` with its bind shape); `instance_camera` (perspective `yfov` or `xfov` + `aspect_ratio`, orthographic `ymag` or `xmag` + `aspect_ratio`) as cameras; `unit` to meters, `Z_UP` / `X_UP` to Y up. Lines and strips are skipped with a warning. |
| `.usda` / `.usdc` / `.usd` / `.usdz` | USD, text or Crate binary (0.4.0 and newer: LZ4 sections, compressed integer and float arrays, inlined values; `.usd` by magic) or a usdz package (its first layer). Every defined, active, non-guide, visible `Mesh` prim: points, faceVertexCounts/Indices (holes skipped, n-gons fanned), normals (`primvars:normals` or `normals`) and UVs (`primvars:st`, `st0`, `UVMap`, `uv` or the first `texCoord2f[]` primvar), indexed or not, any interpolation; `orientation = leftHanded`. Xform ops (`translate`, `scale`, `rotateX/Y/Z`, the six `rotateXYZ` orders, `orient`, `transform`, `!invert!`, `!resetXformStack!`) by `xformOpOrder`. Material names from `material:binding` (inherited) and `materialBind` GeomSubsets. Internal references compose (`class` prims are only drawn through them); time samples use the first sample. Stage `metersPerUnit` (fallback 0.01, as in USD) and `upAxis` become meters, Y up. `Camera` prims (`focalLength` over `verticalAperture`, `projection`) become cameras. Skipped with a warning: external references and payloads, variant sets, PointInstancers. Decoded data is capped at 2 GiB. `self_contained_mesh` packages a loose layer whose UsdPreviewSurface base color textures sit in its folder into a `.usdz` with them, so high polys keep their textures. |
| `.obj` | Triangulated, one vertex per unique `v/vt/vn`, **v flipped** (OBJ is bottom-left). Material names come from `usemtl` (MTL files are never read; they only carry shading data). |
| `.ply` | ascii, binary little/big endian; `x y z`, `nx ny nz`, `s t` / `u v` / `texture_u texture_v`; n-gons fan-triangulated. |
| `.stl` | ascii and binary (size-checked, so binary files whose header says `solid` work); flat normals; no UVs. |
FBX and COLLADA polygons are fan-triangulated with one vertex per unique corner. Missing
normals (OBJ/PLY/FBX/COLLADA) are smooth over welded positions. Missing UVs run
`texturecraft_geom::unwrap::auto_unwrap` (charts within 60° of their seed normal, principal-axis
rotation, shelf packing per material with one texel density). Tangents are MikkTSpace. Limits:
2 GiB files, `MAX_TRIANGLES` triangles, 3 × that many vertices; meshes whose triangles are all
degenerate are refused (MikkTSpace crashes on them).
### Mesh export (`mesh_export`)
```rust
pub fn obj_bytes(mesh: &Mesh, name: &str) -> Vec<u8>;
pub fn glb_bytes(mesh: &Mesh, name: &str, textures: &[GlbTextures]) -> Result<Vec<u8>>;
pub fn glb_export_options() -> ExportOptions; // render GlbTextures with these
pub struct GlbTextures { pub base_color, pub orm, pub normal, pub emissive: Option<Vec<u8>> } // PNG
pub fn usd_bytes(mesh: &Mesh, name: &str, textures: &[Vec<ExportedFile>], format: UsdFormat) -> Result<UsdExport>;
pub fn usd_export_options() -> ExportOptions; // render each material's textures with these
pub enum UsdFormat { Usda, Usdc, Usdz }
pub struct UsdExport { pub bytes: Vec<u8>, pub textures: Vec<(String, Vec<u8>)> } // textures: usda/usdc only
```
USD: one `Mesh` prim (vertex normals and `primvars:st`, `subdivisionScheme = "none"`), one
`materialBind` GeomSubset per material when there are several, and a UsdPreviewSurface material
per material with a UsdUVTexture per map (base color and emissive sRGB; roughness, metallic,
OpenGL normal with scale 2 / bias -1, opacity, clear coat and clear coat roughness raw; black
emissive maps dropped, and both clear coat maps when the coat is black). Meters, Y up.
`.usdc` is a Crate 0.8.0 file; `.usdz` is that layer first plus the PNGs, stored uncompressed at
64-byte aligned offsets; `.usda` / `.usdc` reference `<name>_<material>_<slot>.png` next to the
layer.
GLB: one primitive per submesh, one metallic-roughness material per mesh material with its
textures embedded in the binary chunk (base color sRGB, `alphaMode: BLEND` when it has alpha;
ORM as occlusion + metallic-roughness; OpenGL normal; emissive only when not black).
### Texture export (`export`, `presets`)
```rust
pub fn list_outputs(project: &Project, ts: usize, mesh_name: &str, opts: &ExportOptions) -> Result<Vec<PlannedFile>>;
pub fn render_maps(input: &ExportInput, opts: &ExportOptions) -> Result<Vec<ExportedFile>>;
pub fn write_files(files: &[ExportedFile], dir: &Path) -> Result<Vec<PathBuf>>; // native, atomic
pub fn builtin_presets() -> Vec<ExportPreset>;
pub fn builtin_preset(name: &str) -> Option<ExportPreset>;
pub fn preset_from_json(json: &str) -> Result<ExportPreset>;
pub fn preset_to_json(preset: &ExportPreset) -> Result<String>;
```
- `ExportPreset { name, maps: Vec<MapSpec> }`, `MapSpec { file, format, bit_depth, channels: Vec<(Dest, SourceRef)> }`
(serde JSON, so presets can be user files).
- `Dest`: `R G B A` or `L` (gray; `L` + `A` = gray + alpha).
- `SourceRef`: `Channel { channel, component }` (`Normal` = the **final** normal in the export
normal format), `Virtual { map, component }` (`NormalOpenGl`, `NormalDirectX`, `Glossiness` =
1 − roughness, `AoMixed` = baked AO × AO channel, `F0` = 0.08 × specular level),
`Baked { map, component }`, `Constant(f32)`.
- `ExportOptions { preset, format_override, bit_depth_override, padding, size, normal_format }`;
`Padding::{None, Dilation(n), DilationDefault(n), Infinite}`; `size` must be a power of two
(box filter down, bilinear up).
- File templates: `$project`, `$mesh`, `$textureSet`, `$channel`, `$colorSpace`; names are
sanitized to `[A-Za-z0-9_.-]` (reserved device names get a `_` prefix); case-insensitive
collisions get `_2`, `_3`, … plus a warning.
- A map is written only when one of its sources has data in the texture set (channel present,
map baked, …); alpha from a missing channel is dropped.
- Formats: PNG 8/16, JPEG 8 (q 95), TGA 8, TIFF 8/16, BMP 8, WebP 8 (lossless), EXR 16f/32f
(`Y`, `YA`, `RGB`, `RGBA`, ZIP), HDR 32f. Color maps are sRGB in 8/16-bit and linear in float
formats; data maps are linear; height is stored as `h · 0.5 + 0.5`.
- Final normal: Sobel normal from the height channel (strength = `height_strength`; with 1, a
height change of 1 over 1/16 of the texture width tilts 45°; `+Y` up the image), combined with
the normal channel, then with the baked normal map, by Reoriented Normal Mapping. DirectX
flips green.
Built-in presets:
| Preset | Files (`$mesh_$textureSet_…`) |
|---|---|
| Document channels + Normal + AO | one per document channel (`$channel`), plus `normal` and `ambientOcclusion` (mixed) |
| glTF PBR Metal Roughness | `BaseColor` (sRGB, A = opacity), `OcclusionRoughnessMetallic`, `Normal` (OpenGL), `Emissive` (if present) |
| Unreal Engine (Packed) | `BaseColor`, `OcclusionRoughnessMetallic`, `Normal` (DirectX) |
| Unity HDRP (Mask Map) | `BaseMap`, `MaskMap` (R metal, G AO, B detail = 0, A smoothness), `Normal` (OpenGL) |
| Unity Standard (Metallic Smoothness) | `Albedo`, `MetallicSmoothness` (R metal, A smoothness), `Normal` (OpenGL), `Occlusion` |
| Blender (Principled BSDF) | `BaseColor`, `Metallic`, `Roughness`, `Normal` (OpenGL), `Height` (16-bit), `Emission`, `Specular` |
| Godot 4 (ORM) | `albedo` (A = opacity), `orm` (R AO, G roughness, B metal), `normal` (OpenGL), `emission` |
| OpenPBR (separate maps) | one map per OpenPBR Surface input the set has: `base_color`, `base_metalness`, `specular_roughness`, `specular_roughness_anisotropy`, `coat_weight`, `coat_roughness`, `fuzz_weight`, `fuzz_color`, `fuzz_roughness`, `transmission_weight`, `subsurface_weight`, `emission_color`, `geometry_opacity`, `geometry_normal` (OpenGL), `height` (16-bit) |
| Separate maps | one file per channel, gray where scalar, height 16-bit |
| Mesh maps | every baked map (`$channel` = map id), 16-bit |
### Project file (`project_file`)
```rust
pub struct ProjectFile {
pub project: Project, pub pixels: PixelStore, pub baked: BTreeMap<usize, BakedMaps>,
pub mesh: Option<(String /* ext */, Vec<u8>)>, pub thumbnail: Option<Vec<u8>>,
pub warnings: Vec<String>, // Import warnings, never saved
}
pub fn save_project_bytes(pf: &ProjectFile) -> Result<Vec<u8>>;
pub fn load_project_bytes(bytes: &[u8]) -> Result<ProjectFile>;
pub fn save_project(path: &Path, pf: &ProjectFile) -> Result<()>; // native, atomic
pub fn load_project(path: &Path) -> Result<ProjectFile>; // native
```
`.tcraft` layout (zip, deflate):
| Entry | Content |
|---|---|
| `project.json` | serde JSON of `Project` |
| `mesh.<ext>` | the original mesh file bytes (absent for `builtin:<id>` meshes) |
| `pixels/layer_<id>_<channelId>.bin` | painted layer (or content paint effect) channel |
| `pixels/mask_<id>.bin` | painted mask effect |
| `baked/<ts>_<mapId>.bin` | baked mesh map of texture set `<ts>` |
| `thumbnail.png` | optional, stored |
`.bin`: header `TCTX`, version, width, height, components, tile count (u32 LE each), then per
allocated 64×64 tile `tx`, `ty` (u32 LE) and the raw `u16` LE components (sparse, lossless).
Baked maps: the same header with 0 tiles, then `width × height × components` f32 LE.
Project format version 2 stores baked maps in uniform UV tile blocks, independent of working
tile-resolution overrides. Older projects load their stored bake pixels as-is, without converting
the old layout; their appearance may change until rebaked. Painted layers and cage/skew correction
maps retain their working atlas layout.
Loading runs `Project::validate`, refuses a newer `format_version` (`FormatError::NewerVersion`),
checks every tile against its texture set's resolution and component count, rejects repeated or
out-of-range tiles and trailing data, drops pixels of layers that are in no stack, and caps the
total decompressed size at 8 GiB.
Unreadable bake settings fall back to defaults field by field while readable settings and project
content are retained. Legacy baked-map filenames remain readable; unsupported baked-map types are
skipped. Recovery adds a warning to `ProjectFile::warnings`, displayed in the session log when the
project opens. Structural errors and corrupt pixel data still fail validation.