Further build123d/ocp_vscode integration

[gumyr]

Thank you for creating this project, adding a material system to build123d is one of the long standing roadmap items. py-mat could be the solution, an project independent of build123d but directly supported.

Recently @bernhard-42 added support for PBR into the ocp_vscode viewer (see: https://discordapp.com/channels/964330484911972403/964330777401770025/1483435846081187981) which uses MaterialX materials which can be browsed at the 4 supported sources:

• https://ambientcg.com/list?type=material,
• https://matlib.gpuopen.com/main/materials/all,
• https://polyhaven.com/textures,
• https://physicallybased.info/

We're wondering if you would consider supporting this version of PBR which allows for things like texture maps for wood grain? Possibly something like: steel = bd.Material(name="steel", density=7.8, pbr=bd.Material.gpuopen.load("Brushed Steel")).

I would also hope that we could get to the point where one could add materials to build123d shapes by just setting the material attribute like: my_thing.material = Material(name="Steel", density=7.8).

We're looking forward to collaborating with you.

Cheers, Roger

[gerchowl]

Hi @gumyr — thanks for opening this, and apologies for the slow response.

Short version: yes, we'd love for py-materials to become the material layer for build123d. Materials-as-data has been the library's reason for existing, and hooking into the primary Python-CAD ecosystem is the most useful thing it could be doing.

A few things have moved since you filed the issue:

• @bernhard-42 sent us PR #6 adding Python 3.10 support (merged), and as part of reviewing it we traced the ocp_vscode PBR work back to his threejs-materials library. It already does the heavy lifting for MaterialX: loaders for all four sources you mentioned, MaterialX graph baking, caching, and Three.js MeshPhysicalMaterial output. And we saw the example in ocp_vscode where shape.material = PbrProperties.from_gpuopen(...) already works, with a FutureWarning promising the type will change.
• So the natural next step is figuring out how py-materials and threejs-materials should fit together, with build123d as the canonical consumer via shape.material.

@gumyr — one question for you: how do you see the build123d side of this playing out? Are you thinking of Shape.material as a first-class attribute you'd add to build123d directly, or as a convention we document on the py-materials side? And would you lean toward build123d optionally installing py-materials, or staying fully decoupled so users bring their own? We're happy to implement whichever shape you prefer — just want to make sure we land on something that fits build123d's design taste.

@bernhard-42 — pulling you in directly because you're the lynchpin here: a few open questions before we commit to a direction.

1. How do you see the integration? The options we've been discussing range from py-materials depending on threejs-materials as an optional extra (keeps the two libraries independent), to absorbing threejs-materials into py-materials under a feature flag (single install, but a bigger footprint for users who only want physics properties and don't need PBR rendering). We want to go in whichever direction you think makes sense for threejs-materials' own roadmap.
2. Are you interested in maintaining threejs-materials as the PBR backend long-term? If yes, the optional-extra path is probably the cleanest — py-materials stays lean, threejs-materials stays the single source of truth for PBR loading. If you'd rather hand the PBR story off to py-materials, we can discuss merging.
3. What's your current thinking on offline-first behavior? A lot of py-materials' users are in CI pipelines, headless build farms, and air-gapped scientific environments where network downloads on first-use are painful. Does threejs-materials have (or could it grow) a no-network mode + explicit cache controls?

An alternative worth considering: we could bake the PBR code into py-materials directly (threejs-materials is Apache-2.0, fully compatible), with a feature flag so physics-only users stay lightweight and offline-first. Default install: no PBR, no texture libs, no network-touching code paths. pip install py-materials[pbr] (or similar) enables the full MaterialX story. This is essentially option 1 reframed, but with a single maintenance surface. The downside is it duplicates code you're already maintaining, which is why we'd rather not go this route unless you'd prefer we take the PBR work off your hands.

Whatever you two prefer, we're happy to do the implementation work on the py-materials side. The coordination question is really about how we want the three libraries (py-materials, threejs-materials, build123d) to relate over the long term.

Looking forward to figuring out the right shape of this with you both.

[bernhard-42]

@gerchowl

1 Integration

I think py-materials and threejs-materials serve different purposes:

• py-materials provides physical properties of materials that can be used e.g. for further analysis or in manufacturing
• threejs-materials is a bridge between complex material definitions from MaterialX sources (directly supported and baked) and Blender (baked in Blender and exported as glTF)

The thinking in gumyr/build123d#1270 that Roger (gumyr) and I discussed was the following:

shape.material should work similar to shape.color:

• shape.color = "red" gets resolved by build123d using the Color class to Color(1.0, 0.0, 0.0)
• shape.material = "stainless" gets resolved by build123d using the Material class to py-materials stainless material

With this simple assignment, build123d already has access to e.g. the density of a material useful for mass calculation, but also to all the other properties.

But of course, with py-materials you can do more and I didn't want to replicate the py-materials functionality in build123d. So I think py-materials will be used by engineers to access or create materials and the interface to build123d needs to be easy.

So the current proposal is

shape.material = Material(material: pymat.Material, pbr: threejs_materials.PbrProperties=None)

Afterwards shape.material._material is a py-materials object and the build123d class Material provides proxy properties to py-materials categories so that shape.material.mechanical => shape.material._material.properties.mechanical, ...)

If keyword arg pbr is set, shape.material._pbr is the threejs_material PbrProperties object else None.

As the protocol for OCP VSCode shape.material.pbr exists. The Material property pbr returns self._pbr if not None, else the conversion of py-materials pbr properties (less sophisticated but often sufficient) to PbrProperties.

What this means:

• build123d is decoupled from py-materials as long as the category properties are kept stable
• build123d is decoupled from threejs-materials as long as shape.material.pbr returns a PbrProperties object
• py-materials and threejs-materials are decoupled, but build123d translates py-materials pbr properties to PbrProperties if no extra pbr properties given.

Not saying that this is the right interfacing, but this is what I have implemented in the PR gumyr/build123d#1270

Happy to discuss and change!

---

2 Maintenace

The reason for having built threejs-materials is the Studio mode of OCP VSCode. The output format and three-cad-viewer (the actual viewer Javascript component) are tightly linked: The UV calculation in ocp-tessellate (the triangulation routine that creates meshes from build123d/OCP objects) is reflected in three-cad viewer to properly apply textures, the dict names and structure is mirrored in three-cad-viewer, ... And bugs in rendering often need to be fixed in both, threejs-materials and three-cad-viewer.

As such, my plan was to maintain threejs-materials with a rendering only scope.

Should py-materials and threejs-materials be combined?

Maybe not: There are material categories like liquids, gases, scintillators where my sources (MaterialX and Blender) don't have PBR properties. And there are materials important for CAD (e.g. different woods for laser cut objects) that are currently not in py-materials, but can be added by the user via custom py-materials materials.

+------------------------+
|  py-materials PBR      |
|                        |
|  gas,        |---------+-------------
|  water,      |   alu,  |            |
|  ...         |  steel, |            |
|              |   ...   |            |
+--------------+---------+            |
               |  (wood, ...)         |
               |                      |
               |  threejs-materials   |
               +----------------------+

So my current thinking is:

• I keep the maintenance for threejs-materials as the translator for complex materials from MaterialX and Blender
• py-materials keeps its scope with the simple pbr definitions for its materials (maybe without textures to simplify)

With this users can rely on py-materials only to get both physical material properties and simple rendering properties. And if someone wants nice textured rendering materials, they can add threejs-materials PbrProperties.

So the proposal is that py-materials maintains the simple pbr properties for all materials in its database and I keep maintaining threejs-materials for complex material pbr definitions (and keep it in line with three-cad-viewer)

We just meet in the Material class of build123d

Again, open to discuss this

---

3 Offline

1. The PbrProperties are optional
2. The baking in threejs-materials is done once and then cached in ~/.materialx-cache/

❯ tree .materialx-cache/gpuopen_th_brown_fabric_leather_1k*
.materialx-cache/gpuopen_th_brown_fabric_leather_1k
├── color.png
├── normal.png
└── roughness.png
.materialx-cache/gpuopen_th_brown_fabric_leather_1k.json

with

❯ cat .materialx-cache/gpuopen_th_brown_fabric_leather_1k.json
{
  "id": "TH Brown Fabric Leather",
  "name": "TH Brown Fabric Leather",
  "source": "gpuopen",
  "url": "https://matlib.gpuopen.com/main/materials/all?id=2f568489-6b81-43ab-aa33-cc4f7e32fdce",
  "license": "MIT Public Domain",
  "values": {
    "color": [
      0.800000011920929,
      0.800000011920929,
      0.800000011920929
    ],
    "metalness": 0.0,
    "roughness": 1.0,
    "specularIntensity": 1.0,
    "specularColor": [
      1.0,
      1.0,
      1.0
    ],
    "ior": 1.5
  },
  "textures": {
    "color": "color.png",
    "roughness": "roughness.png",
    "normal": "normal.png"
  },
  "maps_dir": "gpuopen_th_brown_fabric_leather_1k"
}

This should be easy to provide for CI/CD in advance in the repo

---

Summary
It got long, but I tried to explain design and rationale of threejs-materials and how I think it should work with py-materials.
And, as I mentioned, I am absolutely open to discuss our cooperation

[bernhard-42]

Re

An alternative worth considering: we could bake the PBR code into py-materials

The challenge can be the debugging of rendering issues. Sometimes the baker in threejs-materials has an issue, sometimes the rendering in three-cad-viewer, and sometimes both.

So my recommendation would be that I keep the maintenance of threejs-materials to simplify bug fixing in the rendering side

[bernhard-42]

I forgot, to be clear, in my PR build123d needs to import both

from threejs_materials import PbrProperties
import pymat
from pymat import (
    MechanicalProperties,
    ThermalProperties,
    ElectricalProperties,
    OpticalProperties,
    ManufacturingProperties,
    ComplianceProperties,
    SourcingProperties,
)

pymat for type checking only (the category proxies) and PbrProperties to convert pymat pbr properties to PbrProperties

Both should be discussed whether they are the best way to integrate

[bernhard-42]

A bit of a side topic, but maybe you have an opinion about it:

The materialx and openexr dependency of threejs-materials needed for baking MaterialX are currently extra dependencies, since they are only available as binaries up to Python 3.13. On Linux and MacOS, pip install will compile them, but on Windows many users don't have a compiler installed.

What do you think is better:

• make them normal dependencies, failing to install on Windows 3.14 when no compiler is installed, but being at hand on any other platform
• or force every other platform to install 'threejs-materials[materialx]` (as it is implemented now)