cli: support builtin:<id> in info command
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 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.
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.