solvecraft/docs/render-opaque-pbr.md

Opaque product surfaces

This is the first integrated consumer slice of #1004, under #813/#620. It uses the existing Render workspace, product geometry, appearance assignment and PNG job host. There is no second renderer or external material dataset.

Apply and preserve a response

{"command":"appearance.assign","params":{"bodies":["Specimen"],"color":"#b47846","pbr":{"metallic":1,"roughness":0.3,"dielectric_ior":1.5}}}

The Appearance editor has an Opaque PBR checkbox and separate Metallic, Roughness and Dielectric IOR fields. Enabling it explicitly sets opacity to one. View the response in Render or export a product PNG; Design retains its simple color preview. Apply/OK, swatch reuse and component/face targeting use the existing assignment command. A later scalar face override replaces a body's PBR response on that face; it does not inherit the optical response implicitly.

Parameters are finite and bounded: metallic [0,1], perceptual roughness [0.045,1], relative dielectric IOR [1,3]. For PBR, unknown optical fields and nonnumeric/out-of-range opacity refuse before changing the design. PBR requires opacity exactly one. IOR controls the nonmetal fraction's reflection; it does not enable refraction. A library appearance selected by name keeps its complete preset response when pbr is omitted. An explicit color, including a custom look named like a library entry, starts with scalar shading unless a pbr block is supplied. Supplying pbr: null explicitly selects scalar shading. Assignment replaces a look; it is not a partial parameter patch.

Use name with an explicit color to copy an inert look label, including labels that happen to equal a starter.* ID. name and appearance are mutually exclusive. The Appearance editor uses name for owned looks and appearance only for an explicitly selected recipe, so reopening or reusing a copied look does not change its optical values. Explicit unavailable glass recipe requests still refuse; an inert label never enables refraction.

material.create/edit accept the same optional pbr block alongside a default appearance/color. A named PBR default also requires opacity exactly one, even when the command omits pbr; invalid combinations refuse before creating or editing the material. A density-only edit retains the entire existing look. Visual response changes do not modify density, geometry, placement or engineering axes. No grade-specific optical or mechanical values are inferred from a name or color.

Since format 21, pbr is saved inside existing body/face/component and material-default looks. Missing fields retain scalar shading. Format-20 render setups and old looks upgrade without reinterpretation; older readers refuse newly saved files instead of dropping their optical response. Undo/redo, copying and cold reopening use the existing design-owned values, with no external file dependency.

The portable catalog v2 preserves PBR looks and physical-material defaults, alongside validated engineering cards. Explicit scalar v1 export refuses any loss of those records before writing. V1 imports and v2 looks without PBR explicitly select scalar shading and clear a prior PBR response. See local material libraries. In-design swatches retain and reuse the response.

Inspect, replace and inherit a look

appearance.chain is a read-only command. Supply exactly one target: a body, a face index from model.faces with its body, or a component name/ID:

{"command":"appearance.chain","params":{"target":{"body":"Specimen","face":0}}}
{"command":"appearance.chain","params":{"target":{"component":"Housing"}}}

The result contains four steps, ordered face, body, component, material. Each step contains step and look: either null or the full saved look (name, hex color, opacity, and optional pbr). active names the first nonempty step, or is null. Body reads have no face step. Component reads have no face/body steps. Physical materials belong to bodies; a component's material step shows the common material look of its directly owned bodies, or null for mixed/empty components. Root is not an assignable component. Imported paint remains a display fallback outside these four steps, so an all-null chain does not imply a particular viewport color.

appearance.replace rewrites every equal body, face and component override in one undo step. from accepts a library name or a complete look copied from appearance.list's in_design entries. Equality includes the label, color, opacity and all PBR values, so looks with identical names but different responses remain distinct. to accepts a library name or an object with the same look fields as appearance.assign (including inert name with color).

{"command":"appearance.replace","params":{"from":"ABS - Red","to":"Copper - Clean PBR"}}
{"command":"appearance.replace","params":{"from":{"name":"Custom","color":"#abcdef","opacity":0.5},"to":{"color":"#123456","opacity":0.4},"scope":{"bodies":["Specimen"]}}}

Omit scope to replace all stored overrides, including hidden or suppressed ones. Optional scope.bodies selects body overrides and face overrides on those bodies; scope.components selects only those component overrides. These lists combine as a union. A component scope does not expand to its bodies or descendants. Names and numeric component IDs are accepted; duplicate targets count once. Scope targets must exist in the evaluated model/design. An empty target list selects nothing. At most 10,000 scope entries and 100,000 stored overrides are processed; larger requests/designs refuse. The chain read uses the same override budget and at most 100,000 bodies for a component read.

The replacement result is {"count": N}, counting stored overrides rewritten. Invalid values or targets refuse before mutation. A missing source look, empty scope or identical replacement returns count zero without adding undo history or clearing redo. Geometry, placements, density, mass, physical material defaults and engineering records are unchanged. No command opens a dialog. Existing look records support saving/reopening these edits without a format change.

From Material uses the existing clear form of appearance.assign:

{"command":"appearance.assign","params":{"bodies":["Specimen"],"color":null}}
{"command":"appearance.assign","params":{"components":["Housing"]}}
{"command":"appearance.assign","params":{"body":"Specimen","faces":[[5,10,5]],"color":null}}

Clear removes only the selected override. A face then follows its body, a body its component, and finally the physical material's default look. Clear remaining higher-priority overrides when the material should be active. This changes the look without changing density or mass.

Original opaque finish presets

The existing Appearance library includes six additional opaque finishes. Its 20 scalar entries keep their names, colors, opacity and shading behavior. The new names are distinct, and the Appearance editor uses its existing categories, search, swatches and optical fields to select and edit them.

Appearance	sRGB color	Metallic	Roughness
Steel - Satin PBR	#9ea4ac	1	0.40
Aluminum - Satin PBR	#ccd0d6	1	0.30
Copper - Clean PBR	#cc7a50	1	0.25
ABS - Molded PBR	#deded8	0	0.40
PLA - Smooth PBR	#6ea0de	0	0.35
Wood - Oak Uniform PBR Preview	#be925c	0	0.65

Each preset has opacity 1 and an illustrative dielectric IOR of 1.5. The values are original visual studies, not measured optical constants or engineering-grade material properties. Oak is a uniform preview without grain; PLA has no printed layers; satin metals use an isotropic response. A physical material's density and engineering axes remain independent of these visual choices.

The source values live in assets/appearances/opaque_finishes.rs. Assigning a preset saves its values inside the existing look, so a later library update does not change a saved assignment. This addition does not change the design format.

examples/material-finishes.json creates six original radius-10 mm spheres, assigns generic physical materials and applies these finishes through the same commands used by the editor:

solidcraft-cli run examples/material-finishes.json --save target/material-finishes.sc
solidcraft-cli render target/material-finishes.sc --out target/material-finishes.png --width 1600 --height 1000

Actual consumers and color

The installed integrated gpu-viewport and cpu-product image hosts advertise the pbr feature. Requests require it when the captured product scene contains PBR. The static legacy cpu-raster descriptor retains its previous capabilities. No host gains HDRI, refraction, progressive/final rendering or EXR support.

Look colors are decoded from sRGB8 to linear sRGB once in the shared document/scene adapter. PBR GPU vertices carry linear reflectance and optical parameters. The CPU rasterizer interpolates world position and normals with perspective correction; the GPU uses the corresponding fragment interpolation. Both use the original opaque BRDF and three fixed neutral directional lights in Z-up world coordinates. They sum BRDF × relative incident radiance × light cosine, apply per-channel Reinhard preview tone mapping, then encode exactly once. Linear and sRGB GPU attachments have distinct output transfer paths.

This fixed studio has no cast shadows, environment illumination, indirect bounces, emission, anisotropy, coating, absorption or transmission. Lighting magnitudes are relative preview values, not calibrated lux or spectral data. The single-scattering model can darken rough metals. Transparent legacy looks retain approximate sorted alpha blending, including when seen in front of an opaque PBR surface; that is not glass optics. Nondefault exposure/environment controls remain explicitly unsupported.

Scene uploads keep the 128 MiB bound, accounting for the larger PBR vertices. CPU face-map admission accounts for retained optical descriptors. Existing immutable capture, ownership, cancellation, stale-result rejection and PNG export policies remain in effect. Invalid/nonfinite geometry or zero input normals refuse.

Validation and original example

examples/render-opaque-studio.json builds four original spheres and a base, varying metallic fraction and roughness independently while keeping base color. Its values are an illustrative optical study, not engineering data for real grades.

The product offscreen test uses the actual installed callback/pipelines on Vulkan, including both linear and sRGB attachments. For four metal/roughness combinations, each comparison checks 12,454 interior pixels against CPU PNG output; observed mean channel error is below 0.2/255, with no pixels beyond the 12/255 outlier threshold. Silhouettes are excluded because CPU images use 2x supersampling and that test's GPU target uses 1x. This is a scoped parity result, not browser or universal GPU certification.

Command tests check unchanged geometry/mass, atomic refusal, undo/redo, cold reopen, physical default/face precedence, retained scalar format-20 looks upgraded to the current format and explicit v1 catalog refusal. Preset regressions also cover named PBR inheritance, pbr: null, custom looks with matching names, material create/edit refusal without changing history, density-only edits and all six scene responses. A clicked editor regression checks one transaction and reopening the same selected body. Native media and exact current-head gate results belong in the PR. wasm compilation and actual browser interaction are separate evidence.