| Name | cubeforge JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | Generate 3D (STL) files from cube definitions. |
| upload_time | 2025-07-11 20:46:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Teddy van Jerry (Wuqiong Zhao)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
stl
3d
mesh
voxel
cube
geometry
cad
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CubeForge
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
**CubeForge** is a Python library designed to easily generate 3D mesh files (currently STL format) by defining models voxel by voxel. It allows for flexible voxel dimensions and positioning using various anchor points.
## Features
- [x] **Voxel-based Modeling:** Define 3D shapes by adding individual voxels (cubes).
- [x] **Non-Uniform Voxel Dimensions:** Specify default non-uniform dimensions for a model, and override dimensions on a per-voxel basis.
- [x] **Flexible Anchoring:** Position voxels using different anchor points ([`cubeforge.CubeAnchor`](cubeforge/constants.py)) like corners or centers.
- [x] **STL Export:** Save the generated mesh to both ASCII and Binary STL file formats.
- [x] **Simple API:** Easy-to-use interface with the core [`cubeforge.VoxelModel`](cubeforge/model.py) class.
## Installation
**Install from PyPI:**
You can install CubeForge directly from [PyPI](https://pypi.org/project/cubeforge/) using `pip`:
```bash
pip install cubeforge
```
**Install from source:**
You can also clone the repository and install the package using `pip`:
```bash
pip install .
```
## Usage
Here's a basic example of how to create a simple shape and save it as an STL file:
```python
import cubeforge
import os
# Create a model with default 1x1x1 voxel dimensions
model = cubeforge.VoxelModel()
# Add some voxels using the default CORNER_NEG anchor
model.add_voxel(0, 0, 0)
model.add_voxel(1, 0, 0)
model.add_voxel(1, 1, 0)
# --- Or add multiple voxels at once ---
# model.add_voxels([(0, 0, 0), (1, 0, 0), (1, 1, 0)])
# --- Example with custom dimensions per voxel ---
tower_model = cubeforge.VoxelModel(voxel_dimensions=(1.0, 1.0, 1.0))
# Add a 1x1x1 base cube centered at (0,0,0)
tower_model.add_voxel(0, 0, 0, anchor=cubeforge.CubeAnchor.CENTER)
# Stack a wide, flat 3x0.5x3 cube on top of it
tower_model.add_voxel(0, 0.5, 0, anchor=cubeforge.CubeAnchor.BOTTOM_CENTER, dimensions=(3.0, 0.5, 3.0))
# Define output path
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)
output_filename = os.path.join(output_dir, "my_shape.stl")
# Save the mesh as a binary STL file
model.save_mesh(output_filename, format='stl_binary', solid_name="MyCustomShape")
print(f"Saved mesh to {output_filename}")
```
## Examples
The [`examples/create_shapes.py`](examples/create_shapes.py ) script demonstrates various features, including:
* Creating simple and complex shapes.
* Using different default voxel dimensions.
* Overriding dimensions for individual voxels.
* Utilizing various [`CubeAnchor`](cubeforge/constants.py ) options.
* Saving in both ASCII and Binary STL formats.
* Generating a surface with random heights.
To run the examples:
```bash
python examples/create_shapes.py
```
The output STL files will be saved in the [`examples`](examples ) directory.
## API Overview
* **[`cubeforge.VoxelModel`](cubeforge/model.py ):** The main class for creating and managing the voxel model.
* [`__init__(self, voxel_dimensions=(1.0, 1.0, 1.0))`](cubeforge/model.py ): Initializes the model, optionally setting default voxel dimensions.
* [`add_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG, dimensions=None)`](cubeforge/model.py ): Adds a single voxel, optionally with custom dimensions.
* [`add_voxels(self, coordinates, anchor=CubeAnchor.CORNER_NEG, dimensions=None)`](cubeforge/model.py ): Adds multiple voxels, optionally with custom dimensions.
* [`remove_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG)`](cubeforge/model.py ): Removes a voxel.
* [`clear(self)`](cubeforge/model.py ): Removes all voxels.
* [`generate_mesh(self)`](cubeforge/model.py ): Generates the triangle mesh data.
* [`save_mesh(self, filename, format='stl_binary', **kwargs)`](cubeforge/model.py ): Generates and saves the mesh to a file.
* **[`cubeforge.CubeAnchor`](cubeforge/constants.py ):** An [`enum`](/opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/enum.py ) defining the reference points for voxel placement ([`CORNER_NEG`](cubeforge/constants.py ), [`CENTER`](cubeforge/constants.py ), [`CORNER_POS`](cubeforge/constants.py ), [`BOTTOM_CENTER`](cubeforge/constants.py ), [`TOP_CENTER`](cubeforge/constants.py )).
* **[`cubeforge.get_writer(format_id)`](cubeforge/writers.py ):** Factory function to get mesh writer instances (used internally by [`save_mesh`](cubeforge/model.py )). Supports `'stl'`, `'stl_binary'`, `'stl_ascii'`.
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests on the [GitHub repository](https://github.com/Teddy-van-Jerry/cubeforge).
## License
This project is licensed under the [MIT License](LICENSE).
This project is developed and maintained by [Teddy van Jerry](https://github.com/Teddy-van-Jerry) ([Wuqiong Zhao](https://wqzhao.org)).
The development is assisted by *Gemini 2.5 Pro*.
Raw data
{
"_id": null,
"home_page": null,
"name": "cubeforge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "stl, 3d, mesh, voxel, cube, geometry, cad",
"author": null,
"author_email": "Teddy van Jerry <me@teddy-van-jerry.org>",
"download_url": "https://files.pythonhosted.org/packages/4c/f1/1b14a0c58da08596cbd53f5b6a7ab081aa163f4d70bc72b5a802a645b2d0/cubeforge-0.2.0.tar.gz",
"platform": null,
"description": "# CubeForge\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\n**CubeForge** is a Python library designed to easily generate 3D mesh files (currently STL format) by defining models voxel by voxel. It allows for flexible voxel dimensions and positioning using various anchor points.\n\n## Features\n\n- [x] **Voxel-based Modeling:** Define 3D shapes by adding individual voxels (cubes).\n- [x] **Non-Uniform Voxel Dimensions:** Specify default non-uniform dimensions for a model, and override dimensions on a per-voxel basis.\n- [x] **Flexible Anchoring:** Position voxels using different anchor points ([`cubeforge.CubeAnchor`](cubeforge/constants.py)) like corners or centers.\n- [x] **STL Export:** Save the generated mesh to both ASCII and Binary STL file formats.\n- [x] **Simple API:** Easy-to-use interface with the core [`cubeforge.VoxelModel`](cubeforge/model.py) class.\n\n## Installation\n\n**Install from PyPI:**\nYou can install CubeForge directly from [PyPI](https://pypi.org/project/cubeforge/) using `pip`:\n\n```bash\npip install cubeforge\n```\n\n**Install from source:**\nYou can also clone the repository and install the package using `pip`:\n\n```bash\npip install .\n```\n\n## Usage\n\nHere's a basic example of how to create a simple shape and save it as an STL file:\n\n```python\nimport cubeforge\nimport os\n\n# Create a model with default 1x1x1 voxel dimensions\nmodel = cubeforge.VoxelModel()\n\n# Add some voxels using the default CORNER_NEG anchor\nmodel.add_voxel(0, 0, 0)\nmodel.add_voxel(1, 0, 0)\nmodel.add_voxel(1, 1, 0)\n\n# --- Or add multiple voxels at once ---\n# model.add_voxels([(0, 0, 0), (1, 0, 0), (1, 1, 0)])\n\n# --- Example with custom dimensions per voxel ---\ntower_model = cubeforge.VoxelModel(voxel_dimensions=(1.0, 1.0, 1.0))\n# Add a 1x1x1 base cube centered at (0,0,0)\ntower_model.add_voxel(0, 0, 0, anchor=cubeforge.CubeAnchor.CENTER)\n# Stack a wide, flat 3x0.5x3 cube on top of it\ntower_model.add_voxel(0, 0.5, 0, anchor=cubeforge.CubeAnchor.BOTTOM_CENTER, dimensions=(3.0, 0.5, 3.0))\n\n# Define output path\noutput_dir = \"output\"\nos.makedirs(output_dir, exist_ok=True)\noutput_filename = os.path.join(output_dir, \"my_shape.stl\")\n\n# Save the mesh as a binary STL file\nmodel.save_mesh(output_filename, format='stl_binary', solid_name=\"MyCustomShape\")\n\nprint(f\"Saved mesh to {output_filename}\")\n```\n\n## Examples\n\nThe [`examples/create_shapes.py`](examples/create_shapes.py ) script demonstrates various features, including:\n* Creating simple and complex shapes.\n* Using different default voxel dimensions.\n* Overriding dimensions for individual voxels.\n* Utilizing various [`CubeAnchor`](cubeforge/constants.py ) options.\n* Saving in both ASCII and Binary STL formats.\n* Generating a surface with random heights.\n\nTo run the examples:\n\n```bash\npython examples/create_shapes.py\n```\n\nThe output STL files will be saved in the [`examples`](examples ) directory.\n\n## API Overview\n\n* **[`cubeforge.VoxelModel`](cubeforge/model.py ):** The main class for creating and managing the voxel model.\n * [`__init__(self, voxel_dimensions=(1.0, 1.0, 1.0))`](cubeforge/model.py ): Initializes the model, optionally setting default voxel dimensions.\n * [`add_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG, dimensions=None)`](cubeforge/model.py ): Adds a single voxel, optionally with custom dimensions.\n * [`add_voxels(self, coordinates, anchor=CubeAnchor.CORNER_NEG, dimensions=None)`](cubeforge/model.py ): Adds multiple voxels, optionally with custom dimensions.\n * [`remove_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG)`](cubeforge/model.py ): Removes a voxel.\n * [`clear(self)`](cubeforge/model.py ): Removes all voxels.\n * [`generate_mesh(self)`](cubeforge/model.py ): Generates the triangle mesh data.\n * [`save_mesh(self, filename, format='stl_binary', **kwargs)`](cubeforge/model.py ): Generates and saves the mesh to a file.\n* **[`cubeforge.CubeAnchor`](cubeforge/constants.py ):** An [`enum`](/opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/enum.py ) defining the reference points for voxel placement ([`CORNER_NEG`](cubeforge/constants.py ), [`CENTER`](cubeforge/constants.py ), [`CORNER_POS`](cubeforge/constants.py ), [`BOTTOM_CENTER`](cubeforge/constants.py ), [`TOP_CENTER`](cubeforge/constants.py )).\n* **[`cubeforge.get_writer(format_id)`](cubeforge/writers.py ):** Factory function to get mesh writer instances (used internally by [`save_mesh`](cubeforge/model.py )). Supports `'stl'`, `'stl_binary'`, `'stl_ascii'`.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests on the [GitHub repository](https://github.com/Teddy-van-Jerry/cubeforge).\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\nThis project is developed and maintained by [Teddy van Jerry](https://github.com/Teddy-van-Jerry) ([Wuqiong Zhao](https://wqzhao.org)).\nThe development is assisted by *Gemini 2.5 Pro*.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Teddy van Jerry (Wuqiong Zhao)\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Generate 3D (STL) files from cube definitions.",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/Teddy-van-Jerry/cubeforge/issues",
"Homepage": "https://github.com/Teddy-van-Jerry/cubeforge"
},
"split_keywords": [
"stl",
" 3d",
" mesh",
" voxel",
" cube",
" geometry",
" cad"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7a9f4b3396545787edc8690fb013d6d79f5be7ddabfd8c9d218828980e8d0a83",
"md5": "1024c86d079ef66c0605361c41fd3da6",
"sha256": "0c6c8bfe600b9956ce1dbe231948d6b1845b0b0e8086217fa9c412c54f04f536"
},
"downloads": -1,
"filename": "cubeforge-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1024c86d079ef66c0605361c41fd3da6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11245,
"upload_time": "2025-07-11T20:46:41",
"upload_time_iso_8601": "2025-07-11T20:46:41.426919Z",
"url": "https://files.pythonhosted.org/packages/7a/9f/4b3396545787edc8690fb013d6d79f5be7ddabfd8c9d218828980e8d0a83/cubeforge-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4cf11b14a0c58da08596cbd53f5b6a7ab081aa163f4d70bc72b5a802a645b2d0",
"md5": "362e02f6e5b3cbd636da08a9c01b2582",
"sha256": "d60b4fd6a911da307d75163058fcec6f88e0313f3c6fd4bf0e5c6e86819e5f1e"
},
"downloads": -1,
"filename": "cubeforge-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "362e02f6e5b3cbd636da08a9c01b2582",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11937,
"upload_time": "2025-07-11T20:46:42",
"upload_time_iso_8601": "2025-07-11T20:46:42.757171Z",
"url": "https://files.pythonhosted.org/packages/4c/f1/1b14a0c58da08596cbd53f5b6a7ab081aa163f4d70bc72b5a802a645b2d0/cubeforge-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 20:46:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Teddy-van-Jerry",
"github_project": "cubeforge",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cubeforge"
}
