# 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; pub fn import_mesh(path: &Path) -> Result; // native, = read_mesh_file + import_mesh_bytes pub fn self_contained_mesh(name: &str, bytes: Vec, read: &mut dyn FnMut(&str) -> Option>) -> Result; pub fn read_mesh_file(path: &Path) -> Result; // native pub struct MeshFile { pub name: String, pub bytes: Vec, pub warnings: Vec } 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, } ``` | 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_` 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; pub fn glb_bytes(mesh: &Mesh, name: &str, textures: &[GlbTextures]) -> Result>; pub fn glb_export_options() -> ExportOptions; // render GlbTextures with these pub struct GlbTextures { pub base_color, pub orm, pub normal, pub emissive: Option> } // PNG pub fn usd_bytes(mesh: &Mesh, name: &str, textures: &[Vec], format: UsdFormat) -> Result; 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, pub textures: Vec<(String, Vec)> } // 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 `__.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>; pub fn render_maps(input: &ExportInput, opts: &ExportOptions) -> Result>; pub fn write_files(files: &[ExportedFile], dir: &Path) -> Result>; // native, atomic pub fn builtin_presets() -> Vec; pub fn builtin_preset(name: &str) -> Option; pub fn preset_from_json(json: &str) -> Result; pub fn preset_to_json(preset: &ExportPreset) -> Result; ``` - `ExportPreset { name, maps: Vec }`, `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, pub mesh: Option<(String /* ext */, Vec)>, pub thumbnail: Option>, pub warnings: Vec, // Import warnings, never saved } pub fn save_project_bytes(pf: &ProjectFile) -> Result>; pub fn load_project_bytes(bytes: &[u8]) -> Result; pub fn save_project(path: &Path, pf: &ProjectFile) -> Result<()>; // native, atomic pub fn load_project(path: &Path) -> Result; // native ``` `.tcraft` layout (zip, deflate): | Entry | Content | |---|---| | `project.json` | serde JSON of `Project` | | `mesh.` | the original mesh file bytes (absent for `builtin:` meshes) | | `pixels/layer__.bin` | painted layer (or content paint effect) channel | | `pixels/mask_.bin` | painted mask effect | | `baked/_.bin` | baked mesh map of texture set `` | | `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.