SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Original surface-map starter pack
This pack contains 48 original surface recipes and 240 PNG maps, generated at 512 × 512 pixels per map. Each recipe supplies base color, tangent-space normal, roughness, metallic and 16-bit height data. The resources cover metals, coatings, polymers, electronics, additive manufacturing, wood, composites and space-inspired surfaces.
The maps have been authored as reproducible inputs. Their manifest status is
authoring_status: authored, runtime_status: unbound and
appearance_fidelity: illustrative_approximation. No material import, application
render, CPU/GPU scene comparison, measured-material match or photorealistic result
is claimed by this package. The broader material catalog
remains a separate inventory of target concepts; these resources realize selected
concepts without changing their stable MAT-* identities.
Files and authority
| File or directory | Purpose |
|---|---|
| source/recipes.json | Editable authority for the 48 numerical recipes, physical tile dimensions, seeds, concept links and limitations. |
| manifest.json | Generated resource contract, source/generator receipts and encoded/decoded map hashes. |
exports/SURF-*/ |
Five required PNG authoring exports per resource. |
| ../tools/materials.py | Version 1.0.0 offline generator, validator and review-sheet command. |
| ../tools/test_materials.py | Analytic numerical checks and hostile-input admission tests. |
Edit the recipes and regenerate the exports together. Do not repaint a generated PNG and retain its old receipt. A change to the generator, source values, mapping or fidelity requires new validation and updated receipts. The tools use Python 3.11 or later, NumPy and Pillow for local authoring; they add no Python dependency to the Rust application.
Map semantics and renderer binding
The four 8-bit roles are bounded texture inputs intended for a future explicit
renderer adapter. Their manifest consumer is
bounded_texture_input_compatible_not_runtime_bound. Their file shape and color
space do not establish that a particular SolidCraft build imports or applies them.
The 16-bit height role is authoring-only until an adapter explicitly supports
its physical displacement contract; its consumer is
authoring_only_requires_explicit_height_adapter.
| PNG filename | Storage | Interpretation |
|---|---|---|
base_color.png |
RGB, 8 bits per channel | sRGB-encoded color. Decode the sRGB transfer exactly once before linear shading. Values are authored reflectance/F0 approximations for the chosen metallic workflow. |
normal_open_gl.png |
RGB, 8 bits per channel | Linear numerical data. Decode each channel as 2 × sample − 1; use the tangent convention below and renormalize after filtering. |
roughness.png |
Grayscale, 8 bits | Linear numerical roughness, not glossiness. Values are already the authored roughness control; no sRGB transfer or pre-squared microfacet parameter is stored. |
metallic.png |
Grayscale, 8 bits | Linear numerical metallic fraction. The current recipes use opaque metal or dielectric approximations; this channel does not identify an alloy or composition. |
height.png |
Grayscale, unsigned 16 bits | Linear numerical height. Convert to millimetres with the recorded zero and full normalized span. No automatic displacement is enabled. |
There is no packed ORM texture, opacity map or inferred ambient-occlusion map. Ambient occlusion is the constant 1.0: no invented cavity darkening or baked illumination is added. Emission, transmission, coating, anisotropy and volume parameters are not supplied by these five roles. A consumer must report missing support explicitly rather than treating these maps as a complete implementation of the linked material concept.
Normal and height data describe the same local surface relief. An adapter must choose how that relief enters its surface model; applying both the complete height displacement and the complete derived normal perturbation can count the same detail twice. Height-based displacement also requires tessellation, silhouette, bounds and performance validation that this authoring package does not perform.
Color and numerical normalization
The source specifies low and high linear RGB values. The generator interpolates those values using its original periodic tone field, applies the sRGB transfer, then quantizes to 8 bits for base color. It never applies that transfer to normal, roughness, metallic or height channels. The test suite checks the known 18% linear-gray reference: approximately 46.14% sRGB, giving byte value 118. The same 0.18 numerical roughness or metallic value gives byte value 46.
Height is quantized to unsigned 16 bits before the normal field is calculated.
For stored height sample q and the resource's height_span_mm:
normalized_height = q / 65535
height_mm = (normalized_height - 0.5) * height_span_mm
The nominal representable interval is therefore
[-height_span_mm / 2, +height_span_mm / 2]. A recipe need not reach either end.
Do not stretch each image's observed minimum and maximum to fill the interval;
that would change the authored physical amplitude. The normal is the normalized
vector (-dh/dU_mm, -dh/dV_mm, 1), using wrapped central differences of that
quantized height. Consequently, the exported height and normal share the same
scale and relief authority.
Coordinates, scale and repetition
Each whole UV repeat spans tile_mm = [width, height]. These are local physical
surface dimensions in millimetres; maintain them when a CAD body is resized.
SolidCraft's model frame remains Z-up. UV directions must be bound to a reviewed
surface frame rather than inferred from the world axes or camera.
The normal convention is OpenGL +Y, +U right, +V image-up. Image rows increase
downward, so the generator samples row i, column j of an N × N image at:
u = (j + 0.5) / N
v = 1 - (i + 0.5) / N
Both axes use repeat sampling. Pixel centers exclude duplicated boundary samples:
the first and last pixel columns need not be equal, because they are distinct
adjacent samples across a periodic seam. The validator instead compares the
underlying fields at the exact repeat boundaries. It requires a maximum field
residual no greater than 1e-10 and checks the recorded residual against the
recomputed value. Wrapped differentiation preserves relief at those boundaries.
Mip generation, texture filtering and CAD surface-frame continuity still need
validation in the consuming renderer.
Admission bounds
The generator rejects unknown recipe fields, duplicate IDs or JSON keys, invalid concept links, nonobject recipes, nonfinite values and booleans in numeric fields. Names, domains and fidelity limitations must contain nonempty strings.
| Input | Admitted range or rule |
|---|---|
| Source JSON size | At most 4,000,000 bytes. |
| Resource count | 1–64; this source contains 48. |
| Resource ID | Unique SURF- followed by exactly three digits; no paths. |
| Square map resolution | 256, 512, 1024 or 2048; this source uses 512. |
| Seed | Integer from 0 through 2^32 − 1. |
| Each tile dimension | 0.001–10,000 mm. |
| Height span | 0 through one eighth of the smaller tile dimension. |
| Each authored linear color channel | 0–1. |
| Roughness, roughness variation, metallic | 0–1; the resulting roughness field is clamped to 0.02–1 before 8-bit quantization. |
| Each repeat-cycle count | Integer from 1 through resolution / 8. Plain-weave counts must be even; 2/2-twill counts must be multiples of four. |
| Encoded PNG size during admission | At most 16 MiB per map, with exact resolution, channel type and receipt checks. |
The manifest validator checks exact map paths, dimensions, channel counts, bit depths, encodings, pixel extrema and consumer declarations. It rejects unexpected ICC, EXIF or gamma metadata; verifies encoded-file and decoded-pixel hashes; checks positive-Z, near-unit normals; and recomputes normal/height agreement. Changing the availability, AO, repeat, height-zero or normal-convention claims cannot silently pass admission.
Fidelity and engineering independence
All colors, relief, roughness and pattern choices are original illustrative authoring values. They are not optical measurements, manufacturing tolerances, certified color matches or material-selection advice. Applying an appearance must leave density, stiffness, friction, thermal properties, electrical properties, CAD dimensions, joints and simulation state unchanged.
Brushed and machined resources encode directional relief, while true anisotropic reflection remains a renderer task. Anodizing, lacquer, resin-facing composites and thermal coatings are explicitly simplified opaque responses; they do not reconstruct independent optical layers. The 2/2 twill has an original four-cell diagonal crossing pattern, whereas plain weave alternates at each crossing. Both are closed relief patches without individual fibers, openings or fiber scattering.
Wood, cork and regolith are deliberately procedural approximations. The wood patterns are generic grain fields, cork uses original periodic cells, and regolith uses generic relief and color variation. These resources contain no photograph, facility scan, geological sample data or measured lunar scattering. They do not establish species identification, composition, location accuracy or photorealism. The lunar-inspired surfaces remain ground in vacuum, with no airborne dust or atmospheric haze.
FDM resources encode local bead relief, not the original slicer path, support scars, wall outline or printing defects. The aluminium-blanket resource is a local wrinkle field, not a multilayer blanket assembly. None of the maps creates real openings, object silhouettes, deep damage or complete manufacturing geometry. Every resource retains its specific limitations in both the source and manifest.
Resource index
| Resource | Name | Catalog concept |
|---|---|---|
| SURF-001 | Brushed stainless steel | MAT-002 |
| SURF-002 | Cross-satin stainless steel | MAT-003 |
| SURF-003 | Shot-blasted steel | MAT-004 |
| SURF-004 | Galvanized steel spangle | MAT-006 |
| SURF-005 | Face-milled aluminium | MAT-011 |
| SURF-006 | Turned aluminium tool marks | MAT-012 |
| SURF-007 | Bead-blasted aluminium | MAT-014 |
| SURF-008 | Brushed titanium appearance | MAT-019 |
| SURF-009 | Brushed copper appearance | MAT-022 |
| SURF-010 | Machined brass appearance | MAT-024 |
| SURF-011 | Satin nickel appearance | MAT-027 |
| SURF-012 | Solidified solder finish | MAT-165 |
| SURF-013 | Matte white industrial paint | MAT-031 |
| SURF-014 | Black textured powder coat | MAT-032 |
| SURF-015 | Satin red industrial paint | MAT-033 |
| SURF-016 | Grey hammer-finish enamel | MAT-037 |
| SURF-017 | Red orange-peel lacquer surrogate | MAT-204 |
| SURF-018 | Black anodized opaque surrogate | MAT-016 |
| SURF-019 | Fine black ABS housing | MAT-042 |
| SURF-020 | Ivory textured ABS housing | MAT-042 |
| SURF-021 | Machined white POM appearance | MAT-046 |
| SURF-022 | Machined tan PEEK appearance | MAT-047 |
| SURF-023 | Blue silicone jacket surface | MAT-333 |
| SURF-024 | Charcoal technical rubber | MAT-061 |
| SURF-025 | Diamond-pattern TPU grip | MAT-065 |
| SURF-026 | Agglomerated cork surface | MAT-146 |
| SURF-027 | Oiled oak grain approximation | MAT-111 |
| SURF-028 | Walnut grain coat surrogate | MAT-113 |
| SURF-029 | Sanded beech grain | MAT-114 |
| SURF-030 | Natural birch grain | MAT-117 |
| SURF-031 | Birch plywood exposed edge | MAT-121 |
| SURF-032 | Uncoated MDF cut surface | MAT-123 |
| SURF-033 | Carbon 2/2 twill opaque surrogate | MAT-151 |
| SURF-034 | Matte carbon plain weave | MAT-152 |
| SURF-035 | Woven aramid resin surrogate | MAT-157 |
| SURF-036 | Green PCB solder-mask finish | MAT-161 |
| SURF-037 | Blue PCB solder-mask finish | MAT-161 |
| SURF-038 | Epoxy IC package surface | MAT-166 |
| SURF-039 | Opaque black electronics potting | MAT-169 |
| SURF-040 | Orange PLA FDM sidewall | MAT-171 |
| SURF-041 | Grey monotonic FDM top skin | MAT-361 |
| SURF-042 | Black ABS FDM sidewall | MAT-173 |
| SURF-043 | Blue TPU FDM sidewall | MAT-174 |
| SURF-044 | White powder polyamide surface | MAT-175 |
| SURF-045 | White thermal coating surrogate | MAT-491 |
| SURF-046 | Wrinkled aluminium blanket face | MAT-501 |
| SURF-047 | Mare-style regolith surface | MAT-531 |
| SURF-048 | Highland-style regolith surface | MAT-546 |
Rebuild, validate and inspect
Run from the repository root, in an environment with the authoring dependencies:
python3 -B assets/render/starter/tools/materials.py build
python3 -B assets/render/starter/tools/materials.py validate --reproduce
python3 -B -m unittest discover -s assets/render/starter/tools -p test_materials.py -v
python3 -B assets/render/starter/tools/materials.py preview
build regenerates all 240 maps and the manifest from the source authority.
validate --reproduce admits the stored exports, recomputes every map and compares
decoded pixels exactly. Its success result retains runtime_ready: false.
The manifest records SHA-256 receipts for the exact recipe file, generator source, each encoded PNG and each decoded pixel array. Decoded arrays use little-endian byte order for hashing. PNG compression can differ between toolchain versions; an encoded receipt identifies the stored file, while the independent decoded receipt identifies its pixel content. If regeneration differs, inspect the source and toolchain change rather than replacing receipts to conceal a discrepancy.
The focused suite completed 21 passing tests during this authoring iteration. It checks analytic sinusoidal normal direction and magnitude, physical scale over three resolutions, sRGB reference values, periodicity of all pattern kinds, 2/2-twill versus plain-weave crossings, 16-bit round-trip, analytic height/normal coherence and hostile source/manifest/file admission. These are numerical and resource checks, not application renders. They do not establish material-library integration, CAD mapping quality, CPU/GPU agreement or runtime availability.
preview writes an unlit base-color contact sheet to
target/render-starter-review/materials/base-color-contact-sheet.png. It is a
review artifact, not a shaded material thumbnail or renderer result. Keep that
sheet, other inspection images and temporary reports under ignored target/;
do not add them to the production resource collection.
Before admitting these resources as application presets, bind their roles and physical mapping to a pinned renderer contract, verify unchanged engineering state, exercise unsupported-feature handling, and render flat, curved and edge targets with appropriate sampling. Record the actual executor revision and numeric/visual results. The authored source hashes cannot substitute for that runtime evidence.
Clean-room provenance and license
The recipes, periodic fields, tools and exports are original SolidCraft contributor work under MIT OR Apache-2.0. No external texture, photograph, material library, commercial CAD output or third-party artwork was used as an input. The generator uses original numerical constructions and deterministic seeds; it does not infer measured properties from generated images. No GPL, LGPL or AGPL implementation was read, copied or used as an implementation reference.
Every non-Markdown resource and tool is accounted for by an exact entry in the root ATTRIBUTION.md. The wider resource policy and future admission requirements are in the clean-room record and implementation handoff.