solvecraft/assets/render/starter/materials

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.