15 KiB
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)
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)
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)
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 AorL(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};sizemust 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 ash · 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°;+Yup 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)
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
pub fn set_project_open_limit_gib(limit_gib: u32); // subsequent loads, minimum 1 GiB
pub fn project_open_limit_gib() -> u32;
.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, and drops pixels of layers that are in no stack. Total
decompressed project data is limited to 8 GiB by default. Settings › Project › Max project size on
open changes this limit, in GiB, independently of the save CPU and RAM preferences. Each load keeps
the limit it started with; individual resource, mesh, image and entry-count limits still apply.
The limit counts file data, including binary headers and tile coordinates, rather than peak process
memory. Saves and autosaves are not refused by this open limit; raise it to reopen a larger project.
Opening checks the sum of all declared ZIP payload sizes before decompression, including unknown entries, and checks actual reads against the same limit independently. Overlapping ZIP entries are rejected. ZIP indexing is restricted to the final 32 MiB with a 64 MiB read allowance before the 100,000-entry limit can be checked. Baked-map dimensions must agree with the entry size; float data is read in bounded chunks with fallible allocation. Nested archives are not recursively extracted by the project reader. Subsequent image and mesh decoding has separate format-specific limits; the project-open limit is not a combined budget for those decoded assets or the application's heap.
Native saves compress entries in parallel within the configured CPU allowance and an estimated in-flight byte budget. Stored resources and entries larger than that budget stream directly into the destination without a whole-entry temporary buffer. The save RAM percentage is an estimate, excluding compressor, allocator and project-snapshot overhead; it is not a peak process memory cap.
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.