Skip to content

armgit / vork

Public Imported from GitHub
0

Headless 3D and VFX engine for agents. Research preview.

16.1 KB
Raw Blame

Blender import helpers

This directory is a separate GPL-3.0-or-later Blender component; the boundary with vork is scene, geometry, shader and image files. The renderer and std do not import bpy or this component.

Export a scene headlessly:

blender -b --disable-autoexec source.blend --python integrations/blender/export.py -- --out /tmp/vork-scene

Add --animation for scene-sampled clips and camera/light controls. The default preserves evaluated modifiers and reports any missing morph targets; --no-apply-modifiers retains native shape keys and reports omitted modifiers. Subdivision is evaluated by Blender at export: Blender converts its 0..1 edge crease weights to OpenSubdiv sharpness as 10 * weight * weight. The glTF bridge exports that evaluated surface, so no Blender crease weights enter the scene’s OpenSubdiv/USD crease_edge sharpness field. export-report.json records each material variant and substitution, missing geometry/transport features and baked fields. shot.json holds the scene and shot.profile.json its render profile: level 1 for EEVEE or level 2 for Cycles, plus seed and denoise. Source sample counts are recorded in the export report; the selected vork profile owns its sample budget. Render with vork render shot.json --profile shot.profile.json. No EEVEE rendering runs in export.

--bake-curves samples RGB curve transfer functions into lookup textures to reduce shader compilation on large material collections. Upstream values and coordinates remain dynamic, and outside-domain extrapolation stays analytic. Each bake reports its domain, source frame and image encoding: per-channel range-encoded PNG8 with 8-bit storage quantization. These one-row textures use the renderer’s uncompressed path. Native curve lowering remains the default. The API option is MaterialWriter(..., best_effort=True, curve_lookups=True).

Use writer.write_asset(glb_path) to bind material programs per primitive UV signature. A shared source material on meshes with and without UVs gets separate file-level variants; missing source UVs use a reported zero coordinate on that variant. Geometry bytes and source material slots are preserved.

world.translate(world) runs inside Blender 5.2.1 and returns WorldImport: image (a datablock or None), environment (a v2 light node), background and materials. The caller writes image scene-linear pixels to HDR bound as images.world, merges materials into the scene, and uses background in render.background. export.py is one caller; the helper has no benchmark or renderer dependency.

Translation follows the active EEVEE World output, not node insertion order. Supported graphs contain Background with constant strength; constant RGB, native EEVEE Blackbody colour (constant Temperature at/above the RNA evaluator’s 800 K hard limit), or an equirectangular Environment Texture with linear filtering; Generated coordinates through Mapping rotations (including Texture inverse rotation and positive uniform scale); and binary Mix/MixRGB branches driven by Is Camera Ray. Mapping lookup rotations become inverse light transforms after Z-up to Y-up conversion. An authored constant camera branch stays separate from World illumination. An active constant Volume Scatter with Henyey–Greenstein phase becomes an std/fog world medium with its density, its colour as scattering, zero absorption and its anisotropy. Material Volume Scatter/Emission and Principled Volume convert through blender.volume (Blender's Principled Volume formulas, including blackbody). No node interpreter is added to the renderer.

UnsupportedWorld identifies the node/socket when the graph cannot be represented. Procedural colours, fractional mixtures, linked mapping parameters/strength, nonuniform/translated coordinate maps, other/linked volume graphs, groups, and distinct textured camera/lighting backgrounds need further graph translation or renderer support. Unsupported nodes are never silently replaced with a different node's image or constant. Source graphs and materials are not modified.

material_export.MaterialWriter(directory) lowers selected Blender surface graphs into ordinary Slang programs and image inputs. Each program also takes its surface's representative colour as inputs that it reads: base_color (the constant, or the image read through the active UV, feeding Base Color of the heaviest Principled or Diffuse BSDF, else Glossy, followed back through colour adjustments and mixes) and roughness (a constant), and its emission as emission_color and emission_luminance (from the heaviest Emission shader or emitting Principled BSDF). writer.write(material) returns an asset material override ID; merge writer.images, writer.programs and writer.materials into those v2 scene sections. Export geometry with geometry.export_gltf(**options), using the usual Blender glTF operator arguments. geometry.filter_material_overrides(filepath, bindings) filters requested overrides against the emitted glTF/GLB material table before lowering graphs. It warns with the asset path and each missing slot name when Blender drops a slot or its faces; retained overrides apply normally. Authored scene bindings remain strictly validated. The helper preserves native TEXCOORD streams and adds stable active/named UV aliases referencing the same accessors, without copying geometry buffers. It restores temporary source metadata even if export fails. Packed PNG/JPEG bytes, colour spaces and supported sampler settings are preserved without applying Blender's display transform.

This subset handles Object/Normal, active UV and named UV Map coordinates, constant affine Mapping, flat/box images with mapped pixel footprints, RGB Curves, RGBA Mix, Bump, Invert/HSV, Color Ramp, Layer Weight Facing, Principled, Emission and Add/Mix Shader, plus Glossy in best effort mode. The writer selects the current source render engine; direct Compiler callers can pass engine="CYCLES" or engine="EEVEE". It requires no fabricated UVs. Source RGB curves are evaluated through Blender's API and resampled until probes at knots and interval quarters agree within a 16-bit unit-range channel value; unrepresentable curves fail. Height callbacks reevaluate the complete graph at neighbouring pixel offsets. Implicit image vectors use the active render UV. UV graphs read typed attributes with gradients and retain Blender UV orientation through Mapping/Bump. Missing source UV streams fail installation instead of receiving invented coordinates. In strict mode, unsupported nodes and instancer coordinates, image Color with linked Alpha, linked mapping parameters, subsurface/anisotropic/thin-film responses, the reflection substitutions below and material volume/displacement raise UnsupportedMaterial with the source material/node/socket. Nonzero unsupported responses are never dropped. Image Texture Alpha samples the stored Alpha channel independently of Color. The emitted Principled response uses vork's OpenPBR shading; it does not promise identical Blender BSDFs. No source datablock is edited.

display.translate(scene) writes render.display with std/standard, std/agx or blender/filmic; exposure, gamma, dither intensity and applicable looks are inputs. White balance appends post/white_balance to render.compositor and affects linear outputs. Non-sRGB display devices, other views (including ACES 1.3), custom display curves and mismatched looks raise named errors. This does not translate compositor node trees. Wasp Bot's authored custom red display curve remains unsupported.

Licence boundary

The Blender integration is GPL-3.0-or-later (LICENSE). It exchanges scene files and CLI invocations with vork. It is published in this repository as a separate component and is not part of vork's release archives or npm/PyPI packages; no renderer, SDK or library code imports it. This marking records the integration’s existing licence boundary; it does not relicense the renderer.

Partial scene ingestion

For scene ingestion, MaterialWriter(directory, best_effort=True) enables partial surface translation. Failed numeric producers use the destination socket's source default; failed shader closures use that node's Color/Base Color or the material viewport colour as a diffuse surface. Other shader branches remain translated. Each returned material ID has a writer.reports[id] record with its status and material/node/socket/reason/replacement substitutions. Persist these records with the scene; a partial status does not certify visual fidelity. Linked displacement and volume on surface materials are reported and omitted. Supported volume-only Emission and Volume Scatter graphs produce numeric medium programs. Other volume-only graphs receive a transparent surface with an explicit missing transport report so they do not become opaque black occluders. Strict translation remains the default. No source graph is modified.

Native lowering also supports EEVEE Diffuse BSDF, Glossy (below), neutral Transparent coverage, instance-bound node groups, reported Generated-coordinate approximation, Geometry Position/Normal/True Normal/Tangent/Incoming/Backfacing, Fresnel, Layer Weight Fresnel, Blackbody, scalar/vector Mix and the admitted Math operations in blender/nodes. Cycles rough Diffuse retains a named approximation in best effort mode. Glass BSDF uses native GGX reflection/refraction; Cycles Beckmann and Multiscatter GGX are reported as single-scatter GGX approximations in best effort. Active-render-UV tangent Normal Map uses the imported tangent frame; named UV and other spaces remain reported fallbacks. Unsupported Principled responses preserve the other translated sockets.

vork's material is OpenPBR only, so three Blender reflection choices become their nearest OpenPBR equivalent. Each is a reported substitution in best effort mode and raises UnsupportedMaterial in strict mode:

  • Glossy's constant-colour reflection becomes OpenPBR dielectric Fresnel. The IOR makes normal-incidence reflectance equal the colour's brightest channel (specular_weight carries the rest of an HDR colour) and specular_color carries its hue, so head-on reflections match and grazing reflections are brighter than Blender's: they rise toward the colour's hue at full brightness (a grey Glossy rises toward white). On a gold GGX Glossy sphere the mean colour moved by under 0.002.
  • Cycles Ashikhmin–Shirley, Beckmann and Multiscatter GGX Glossy become GGX of the same roughness. Ashikhmin–Shirley highlights come out sharper and brighter than Cycles' at equal roughness (about 18% brighter sphere mean at roughness 0.3).
  • Cycles single-scatter GGX Principled metals become multiscatter-compensated GGX in the path integrator: rough metals keep the energy single scattering loses, so they render slightly brighter than Cycles' GGX (about 1% at roughness 0.5), as Cycles' Multiscatter GGX does.

export.py --bake-values RESOLUTION enables selective CPU value baking during scene export. Resolution is explicit; the CLI requires applied render modifiers. Shared glTF meshes receive separate material tables for each identified source object, while accessor/geometry bytes stay shared. Ambiguous or repeated source object occurrences retain reported socket defaults instead of sharing a world-field bake. Animated exports report that these textures are source-frame snapshots. Bakes require finite, nondegenerate UV triangles inside one image tile, with no overlapping interiors; shared edges are allowed. Unsupported UV layouts and missing source images retain reported defaults. Receipts include the UV layer and source bake margin. No automatic unwrap changes the authored coordinates.

writer.write(material, bake_object=obj, bake_resolution=resolution) adds selective CPU emission baking when best effort cannot lower a numeric producer. Resolution is explicit. These materials and textures belong to that evaluated object, UV layout and frame; bind them per object and export fresh bakes for changed poses. Bakes bind float EXR images directly. Unmodified EXR/HDR source bytes are retained; dirty/generated float images are saved as linear EXR snapshots. The renderer uses filterable RGBA16F with float mips, preserving negative/HDR values (magnitudes clamp at65504), without PNG8 quantization or block compression. Optional curve lookup baking still uses its explicitly reported PNG8 encoding. writer.reports[id].bakes records provenance. View/ray-dependent fields and unavailable source context remain reported defaults. Baking retains closures and cannot reconstruct hair or volume transport.

animation.export_clip(path, asset_name, apply_modifiers=...) exports scene-sampled glTF animation and returns clip layers plus emitted channel paths/skin counts and omission findings. Apply Modifiers preserves evaluated geometry and may remove shape keys; missing emitted morph targets are reported per object. Disabling it retains morph targets and reports omitted non-armature modifiers. animation.sample_controls(scene, bindings) samples native camera/light transforms and numeric controls; bindings map explicit vork node names to source objects. Merge its returned layer and the clip layers into scene animation. Source frame/subframe are restored. Frame samples use linear interpolation; camera cuts use STEP when every source camera has a binding. Projection/sensor-fit/DOF-enable changes are reported as initial-configuration snapshots. Orthographic DOF and focus planes at or inside focal length are reported and omitted. Apply sample_controls’s returned disabled_dof names by removing DOF from those camera nodes; these clips cannot retain thin-lens DOF for their full range.

Render settings and source selection are restored after geometry and control sampling. Static and animated area lights retain object scale. Light colour is exported as color, and use_temperature as temperature (kelvin; vork multiplies by std.color's blackbody, a Planck integration without Blender's constant colour above 12000 K); energy includes 2 ** exposure. Unnormalized lights retain a reported normalized-energy approximation. Shadow technique and map resolution are render-profile choices and are never exported per light. Disabled source shadows become shadowed_by: []. Light type or normalization changes retain initial numeric data across the clip; shape and shadow toggles retain their initial configuration and report it. Animated material values remain source-frame snapshots and are explicitly reported.

Volume-only Emission and Volume Scatter graphs export native numeric medium programs, leaving no opaque fallback shell. Surface-dependent fields remain reported defaults because medium inputs have no surface UV/frame context. Unsupported scattering phases use a reported Henyey-Greenstein approximation. In best effort mode, Light Path uses reported primary-camera values; shadow and secondary-ray contexts are approximated. This is a named fidelity boundary.

Generated coordinates in best effort use normalized imported rest bounds; source ORCO/manual texture-space data is not carried by glTF. Strict mode rejects that missing source context. Object and UV coordinates retain their explicit contracts.

Standard-tone display curves export as a compositor before white balance, exposure and OCIO. Alpha and control outputs are preserved. Every export reports that curves also affect linear EXR/render-image beauty; strict translation refuses that change. Film-like tone and vertical endpoint extrapolation are reported omissions.

In best effort, Principled Subsurface Weight, Base Color, Subsurface Scale and Subsurface Radius can drive native opaque Burley diffusion. The report identifies the source scattering model and the native approximation. Cycles anisotropy uses native transport similarity; EEVEE keeps its isotropic diffusion response. Strict translation rejects this approximation. The complete active shader graph must be proven opaque, nontransmitting and thick: Mix/Add Shader, reroutes, muted bypasses and group instances participate in that proof. Unsupported or dynamic transport fields keep the other Principled responses and report omitted subsurface. Bounded media also omit diffusion with a report while retaining the medium.

Denoising settings map to guides, prefilter and quality.