Hybrid Neural + Exact Periodic Procedural PBR Material Synthesizer
hypbr synthesizes seamlessly tileable, physically calibrated 15-map PBR material sets (glTF 2.0 ORM, 16-bit height, OpenGL/DirectX tangent normals, 8-azimuth horizon-based AO, bent normals, curvature, anisotropy, specular, and subsurface thickness) at arbitrary resolution with zero border seams.
- Exact Periodic Procedural Synthesis: Pure NumPy/PyTorch circular-padded microstructure generators across metals, stones, ceramics, fabrics, wood, and hard-surface panels — ~0.35s per material with
0.00 pxseam error. - 47-Node Composable PBR Graph: Editable JSON node graph with analytic bevels, Weickert structure tensors, Reoriented Normal Mapping (RNM), 8-azimuth Horizon-Based Ambient Occlusion (HBAO) + Bent Normals, and Kaplanyan/Toksvig Specular Anti-Aliasing.
- Optional Neural Photo-to-PBR: Calibrate real macro photographs through Apple Depth Pro (metric depth prior) and DeepBump ONNX (micro-relief tangent normals) before feeding into the circular-padded 47-node graph.
git clone https://github.com/wrong-nebula/hypbr.git
cd hypbr
pip install -e .For neural photo-to-PBR (hypbr photo), also install the optional neural extras and Apple Depth Pro:
pip install -e ".[neural]"List built-in procedural materials:
hypbr listSynthesize a single seamless 15-map PBR material at 1024x1024 (with optional physical weathering --wear 0.0..1.0):
hypbr synth patinated_verdigris_bronze --size 1024 --wear 0.35 --out ./output/pbrPhysically blend two materials using Unreal/Substance-style HeightLerp (height, cavity, or linear) with recomputed 8-azimuth HBAO, curvature, and ORM:
hypbr blend ./output/pbr/hammered_copper_dimple ./output/pbr/venetian_plaster_trowel --mode cavity --factor 0.45 --out ./output/pbr/copper_plasterInspect any synthesized or blended material in a local interactive Three.js PBR studio (channel switcher, live displacement, UV tiling, orbit lighting):
hypbr preview ./output/pbr/patinated_verdigris_bronzeSynthesize and export directly to game engines & 3D tools in one command:
hypbr synth patinated_verdigris_bronze --size 1024 --export unity,godot,unreal,blender,threejs,vulkan --out ./output/pbrOr export any existing hypbr material directory:
hypbr export ./output/pbr/patinated_verdigris_bronze --target all --out ./output/engines/bronzeVerify seamlessness, normal validity, ORM packing, and physical PBR bounds (CI-ready exit code):
hypbr verify ./output/pbr/patinated_verdigris_bronze --jsonSynthesize a machined hard-surface panel (hardops_plate):
hypbr synth hardops_plate --size 512 --out ./output/pbrSynthesize the full built-in procedural catalog:
hypbr synth all --size 512 --out ./output/pbrExport and inspect a 47-node PBR graph preset as JSON:
hypbr dump-preset v13-default > my_graph.jsonConvert a macro photograph to 15 seamless PBR maps (requires optional Depth Pro + ONNX Runtime):
hypbr photo path/to/surface.jpg --preset v13-default --tileable --out ./output/photo_pbrfrom hypbr import list_materials, synthesize_material
for item in list_materials()[:5]:
print(item["id"], "-", item["category"])
out_dir = synthesize_material(
"damascus_folded_steel",
out_dir="./output/damascus",
size=1024,
seed=42,
)
print("Saved 15 PBR maps to:", out_dir)from hypbr import export_material, synthesize_material
raw = synthesize_material("patinated_verdigris_bronze", "./output/bronze", size=1024)
export_material(raw, "./output/unity/bronze", target="unity")
export_material(raw, "./output/godot/bronze", target="godot")
export_material(raw, "./output/unreal/bronze", target="unreal")
export_material(raw, "./output/threejs/bronze", target="threejs")
export_material(raw, "./output/blender/bronze", target="blender")
export_material(raw, "./output/vulkan/bronze", target="vulkan")import json
from hypbr import PRESETS
graph = PRESETS["v13-default"]
print(f"Nodes in v13-default: {len(graph['nodes'])}")
with open("custom_graph.json", "w") as f:
json.dump(graph, f, indent=2)See runnable scripts in examples/synthesize_pbr.py, examples/export_engines.py, examples/blend_and_weather.py, and examples/custom_graph.py.
| Target | Normal Convention | Channel Packing & Ready-to-Import Assets |
|---|---|---|
unity |
OpenGL +Y |
BaseMap.png, NormalMap.png, MetallicSmoothness.png (R=Metallic, A=1-Roughness), OcclusionMap.png, HeightMap.png, unity_material.json |
unity-hdrp |
OpenGL +Y |
BaseMap.png, NormalMap.png, MaskMap.png (R=Metallic, G=AO, B=Detail, A=1-Roughness), HeightMap.png, unity_material.json |
godot |
OpenGL +Y |
Godot 4 material.tres (StandardMaterial3D with deep parallax & ORM channels), albedo.png, orm.png, normal.png, height.png |
unreal |
DirectX -Y |
T_BaseColor.png, T_Normal_DX.png (green-flipped), T_BentNormal_DX.png, T_ORM.png, T_Height16.png, ue5_material.json |
blender |
OpenGL +Y |
import_blender.py (one-click Blender 4.x Principled BSDF node tree with sRGB/Non-Color setup) + textures |
threejs |
OpenGL +Y |
material.js ES module (MeshPhysicalMaterial factory with SRGBColorSpace / NoColorSpace & anisotropy) + textures |
gltf |
OpenGL +Y |
material.gltf (glTF 2.0 pbrMetallicRoughness + occlusionTexture + normalTexture), baseColor.png, orm.png, normal.png |
glb |
OpenGL +Y |
Single self-contained binary <name>.glb preview sphere with embedded albedo, ORM & normal maps (drag-and-drop in Blender, Three.js, Godot, Quick Look) |
vulkan |
OpenGL +Y |
vulkan_manifest.json (VK_FORMAT_* bindings & ktx create UASTC/BC5 commands), orm_unorm.png, normal_rg_bc5_src.png, height_r16.png |
materialx |
OpenGL +Y |
material.mtlx (MaterialX 1.38 standard_surface + displacement for OpenUSD, Houdini, Maya, RealityKit) + textures |
usd |
OpenGL +Y |
material.usda (OpenUSD ASCII UsdPreviewSurface with exact scale=(2,2,2) / bias=(-1,-1,-1) normal decoding for RealityKit, visionOS, Omniverse) + textures |
Every material synthesis writes a clean, renderer-ready directory compatible with glTF 2.0, Three.js, Blender, Unreal Engine, and Unity:
| File | Bit Depth / Channels | Description |
|---|---|---|
albedo_delit.png |
8-bit sRGB | De-lit physical base color |
normal.png |
8-bit RGB | Tangent-space normal map (OpenGL +Y, optional DirectX -Y) |
bent_normal.png |
8-bit RGB | Average unoccluded hemisphere direction from 8-azimuth HBAO |
height.png |
8-bit Gray | Linear displacement / POM heightmap |
height16.png |
16-bit Gray | Precision 16-bit linear heightmap (zero banding) |
ao.png |
8-bit Gray | 8-azimuth Horizon-Based Ambient Occlusion |
roughness.png |
8-bit Gray | Physical roughness with Toksvig Specular AA |
metallic.png |
8-bit Gray | Physical metallic mask |
orm.png |
8-bit RGB | Packed glTF 2.0 texture (R=AO, G=Roughness, B=Metallic) |
curvature.png |
8-bit Gray | Multi-scale signed curvature (0.5 neutral) |
cavity.png |
8-bit Gray | Concave crevice mask |
edge_wear.png |
8-bit Gray | Convex ridge wear mask |
anisotropy.png |
8-bit RGB | Tangent flow direction + anisotropy strength |
specular.png |
8-bit Gray | Dielectric specular level / F0 modulation |
thickness.png |
8-bit Gray | Inverted ambient thickness for subsurface scattering |
preview.png |
8-bit sRGB | Shaded studio preview |
hypbr/procedural.py: Exact periodic FBM, Voronoi, weave, tile, and metal microstructure heightfield generators.hypbr/normal_graph.py: Composable 47-node PBR graph engine (RNM blending, Weickert structure tensors, analytic SDF bevels, GPU-accelerated 8-azimuth HBAO + bent normals, Toksvig Specular AA, ORM packing).hypbr/synthesize.py: High-level material synthesis API combining periodic heightfields, physically based multi-tone albedo/metallic rules, and the 15-map export pipeline.hypbr/weightcode.py: Zero-training analytic weight surgery (exact 9-mode orthonormal 3×3 spatial kernel filtering, SVD energy shrinkage, circular Conv2d padding, and 4-quadrant partition-of-unity tileable blending).hypbr/depthpro_pbr.py: Optional Apple Depth Pro + DeepBump ONNX neural relief extractor with 4-rotation perspective cancellation and GPU-accelerated Gaussian/HBAO kernels (HYPBR_DEVICE=cpu|mps|cuda).hypbr/exporters.py: Zero-dependency engine & standard exporters (unity,unity-hdrp,godot,unreal,blender,threejs,gltf,glb,vulkan,materialx,usd).hypbr/blend.py: Physically based 16-bit HeightLerp / cavity material blending (hypbr blend) with linear-light albedo mixing and recomputed HBAO/curvature/ORM.hypbr/preview.py: Zero-dependency local interactive Three.js PBR studio viewer (hypbr preview) with per-channel inspection, tiling, and displacement controls.hypbr/verify.py: Automated seamlessness, tangent normal validity, Helmholtz curl, ORM consistency, and PBR calibration QA verifier (hypbr verify).hypbr/cli.py:hypbrcommand-line interface.
Code is released under the MIT License.
Note on optional neural weights: If you use the optional
hypbr photoneural mode with Apple Depth Pro checkpoints, those external weights are subject to Apple'sapple-amlrresearch license. Pure procedural synthesis (hypbr synth) has zero external model dependencies and is 100% MIT licensed.


