-
This guide explains how to use the code in the paper to predict polycube structures using the DDPM-Polycube algorithm.[1]
-
The implementation of this code is mainly based on Python and the 3D software Blender. It uses Python third-party libraries and Blender's built-in libraries. The following table lists the Python libraries and Blender version used in this workflow.
| Environment/Library/Software | Version | Description |
|---|---|---|
| Blender | 4.3.2 | Built-in libraries bpy. |
| Python | 3.9 | / |
| numpy | 1.23.5 | Version consistency is recommended to avoid compatibility issues. |
| torch | 1.10.1+cu102 | / |
- Introduction to the Blender interface and basic operations
The image below shows the basic Blender interface. In this code workflow, we mainly focus on three areas: the viewport, also called the 3D Viewport, outlined in yellow; the code area, also called the Text Editor, outlined in red; and the file area, also called the Outliner, outlined in green. The File button outlined in blue is also important.
(1) Yellow rectangle: Viewport
Used to display the model and adjust the current view. The yellow oval area is used for view adjustments. Drag the top coordinate axis in the yellow oval with the mouse to rotate the view. Similarly, drag the magnifying glass icon to zoom, and drag the hand icon to move the view. These operations allow you to inspect model details in the viewport.
(2) Red rectangle: Code Area
Used for switching, browsing, and running code. The left red oval outlines a booklet-like icon for switching between different code files, while the right red oval outlines a triangle icon for executing code.
(3) Green rectangle: File Area
Lists all current models. Focus on the eye icon outlined in the green oval to show or hide models. Double-click the model name with the mouse to rename it.
(4) Blue rectangle: File
Click this when importing models. For example, to import an FBX file, click File -> Import -> FBX (.fbx) and select the desired FBX file to import.
- Explanation of subdirectories in this directory
| Subdirectory | Purpose |
|---|---|
diff_32_steps_stl |
Stores the reconstructed 32-step diffusion triangle mesh result. |
pics |
Stores images showing the diffusion process. |
src |
Stores source code. |
testing_models |
Stores the test model files in FBX format. |
tmp |
Mainly stores various intermediate files output during the coding process. |
training_data |
Stores the constructed training data. |
v_cos |
Stores the point coordinates of the model used for the training set and their connection relationships. |
weights |
Stores the trained neural network weights. |
The overall code is divided into two parts: one part is executed directly as Python files, and the other part is executed as Python-based scripts within Blender.
Before executing the code, there are two preparation steps:
-
Double-click to open the Blender file in the
srcdirectory. -
Import the model into Blender. As mentioned earlier, use
File -> Import -> FBX (.fbx)to import a model from thetesting_modelsdirectory into Blender. Note the imported model's name in the file area. If the name is nottest, rename it totest.
The most important preparation is to include the parameters g1 and g2 when running file 2.
Specifically, when testing a model, you can select possible unit combinations based on the model's genus or other available information. For two units, you need to enter g1 and g2.
g1represents the-x-axis portion of the2x1grid.g2represents the+x-axis portion of the2x1grid.- If you believe the model consists of only one unit,
g1should be set to-1, andg2should be filled in with the possible unit number.
The numbering of the basic units is shown in the following figure:
For example, after importing the rod model in our dataset, because its genus is 1, we may assume that its -x part is a cube and its +x part is a torus. In this case, we enter the parameters g1=0 and g2=3 when running file 2.
If we import a genus-0 model, we can try a single basic unit cube. In this case, the inputs should be set to g1=-1 and g2=0.
It is important to note that because we want to select the best results, we may need to run the program multiple times for each model, selecting different but reasonable basic unit combinations. For example, a genus-1 model might use g1=0, g2=3 or g1=0, g2=6 to try different diffusion processes.
After preparation, you can start executing the code. The table below lists the execution order:
| Step Number | Specific Execution Content |
|---|---|
| 1 | Execute File 1 in Blender. |
| 2 | Execute Python file 2 from the command line:python 2_Testing.py --g1 <g1_value> --g2 <g2_value> |
| 3 | Execute Python file 3. |
| 4 | Execute File 4 in Blender. |
| 5 | Execute Python file 5. Optional. |
In general, when testing a model, you first need to calculate genus-related information, enumerate all possible basic unit combinations based on the genus, convert these basic combinations into parameters g1 and g2, and then use the above program to batch-generate polycube results for these cases.
Finally, based on the polycube results generated with different parameters, you can determine the optimal parameters and the corresponding polycube.
In addition, we also provide model training code, which can be used if you need to train the model.
The results of the polycube recognition can be viewed in the following files in the diff_32_steps_stl folder:
step32.k: can be opened with LS-DYNA.step32.stl: can be opened with various 3D modeling software, including Blender.
If you executed files 4 and 5, you can also see images of the entire diffusion process in the pics folder.
Some of this code refers to the public sample code of How Diffusion Models Work.
[1] Y. Yu, Y. Fang, H. Tong, J. Liu, and Y. J. Zhang, "DDPM-Polycube: A Denoising Diffusion Probabilistic Model for Polycube-Based Hexahedral Mesh Generation and Volumetric Spline Construction," arXiv:2503.13541, 2025.