{"id":28451528,"url":"https://github.com/hummat/bproc-pubvis","last_synced_at":"2026-04-30T19:31:45.306Z","repository":{"id":266963957,"uuid":"894898318","full_name":"hummat/bproc-pubvis","owner":"hummat","description":"Publication-ready visualization of 3D objects and point clouds in seconds.","archived":false,"fork":false,"pushed_at":"2026-04-15T06:16:51.000Z","size":31196,"stargazers_count":41,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-15T07:31:19.775Z","etag":null,"topics":["3d-visualization","blender","blenderproc","cli","mesh","point-cloud","python","rendering","scientific-visualization"],"latest_commit_sha":null,"homepage":"https://hummat.github.io/bproc-pubvis/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hummat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-11-27T07:45:46.000Z","updated_at":"2026-04-15T06:16:50.000Z","dependencies_parsed_at":"2024-12-07T13:55:23.684Z","dependency_job_id":null,"html_url":"https://github.com/hummat/bproc-pubvis","commit_stats":null,"previous_names":["hummat/bproc-pubvis"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/hummat/bproc-pubvis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummat%2Fbproc-pubvis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummat%2Fbproc-pubvis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummat%2Fbproc-pubvis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummat%2Fbproc-pubvis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hummat","download_url":"https://codeload.github.com/hummat/bproc-pubvis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummat%2Fbproc-pubvis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32475191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-visualization","blender","blenderproc","cli","mesh","point-cloud","python","rendering","scientific-visualization"],"created_at":"2025-06-06T16:11:25.902Z","updated_at":"2026-04-30T19:31:45.300Z","avatar_url":"https://github.com/hummat.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [BlenderProc](https://github.com/DLR-RM/BlenderProc) Publication Visualization\n\nPublication-ready visualization of 3D objects and point clouds in seconds.\n\n| Mesh                       | Point Cloud              | Mesh + Depth                           |\n|----------------------------|--------------------------|----------------------------------------|\n| ![mesh](examples/mesh.png) | ![pcd](examples/pcd.png) | ![mesh_depth](examples/mesh_depth.png) |\n\n_Head over to the repository's [**GitHub** Pages site](https://hummat.github.io/bproc-pubvis) for a prettier and more\ninteractive version of this README!_\n\n\u003e **Design philosophy:** Following [Andrej Karpathy](https://github.com/karpathy) and KISS.\n\n## Installation\n\nRequires [`uv`](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.11.\n\n```bash\nuv pip install git+https://github.com/hummat/bproc-pubvis.git\nuv run blenderproc pip install loguru tyro\n```\n\nThe first call of `blenderproc` will download [`Blender`](https://blender.org). If you already have a local\ninstallation, you can use\n`--custom-blender-path path/to/blender` (this also needs to be used for all subsequent calls of `blenderproc`).\n\n## Basic Usage\n\nTo render a mesh (or point cloud if the input is one), simply run:\n\n```bash\nuv run blenderproc run main.py --data path/to/3d.obj\n```\n\nThe following options can be added to:\n\n* **save** the rendered image: `--save path/to/output.png`\n* **export** the object: `--export path/to/output.obj` (use `.glb` for a web-friendly format)\n* render the mesh as **point cloud**: `--pcd True` (or a target count, e.g. `--pcd 2048`)\n* render the mesh as **depth** image: `--depth ray_trace` (use `z_buffer` for Blender’s z-buffer)\n* render the mesh as **point cloud** from projected **depth** image: `--pcd True` `--depth ray_trace`\n* keep the mesh when rendering as point cloud or wireframe: `--keep-mesh` (used in the _Mesh + Depth_ example above)\n* create an **animation**: `--animate turn` (use `--frames` for length, default `72`, and `--fps` for playback speed, default `20`)\n\nYou can test you render settings using any of the `Blender` primitives (`monkey`, `cube`, `sphere`, `cone`,\n`cylinder`, ...) as the first argument.\n\nUse `uv run blenderproc run main.py -- --help` to see all available options and their descriptions (the `--` passes flags through BlenderProc to Tyro).\n\n| Mesh                                     | Point cloud                   | Depth                                      |\n|------------------------------------------|-------------------------------|--------------------------------------------|\n| ![mesh](examples/mesh.png)               | ![pcd](examples/pcd.png)      | ![mesh_depth](examples/mesh_depth.png)          |\n| `suzanne` (primitive, positional)        | `--pcd True` `--light very_bright` | `--pcd 1024` `--point-size 0.01` `--depth ray_trace` `--keep-mesh` |\n\n## Basic Options\n\n* `--resolution`: Change the resolution of the rendered image (default: `512x512`)\n* `--center`: Center the object inside a unit cube (enabled by default)\n* `--scale`: Scale the object to fit into a unit cube (enabled by default)\n* `--rotate`: Rotate the object using `XYZ` Euler angles in degrees (default: `[0,0,-35]`)\n* `--show`: Show the rendered image in a window (enabled by default if `--save` is not provided)\n* `--cam-location`: Set the camera location (default: `[1.5,0,1]`)\n* `--cam-offset`: By default, the camera looks at the origin `[0,0,0]`. Use this option to change the look-at point.\n\n## Additional Options\n\nSome examples of additional options to customize the rendering are shown below.\n\n### Color\n\nTo change the color of the rendered object, use the `--color` option using either any of the predefined colors (e.g.\n`pale_violet`), choosing from those at random (`random_color`), a completely random color (`random`), or a three-tuple\nof RGB values in range 0-1, e.g `0.8 0.5 0.2`. Any of the\n`matplotlib` [colormaps](https://matplotlib.org/stable/users/explain/colors/colormaps.html) can be used as well.\nThe background color can be changed using the `--bg-color` option.\n\n\u003e Note: Use `--seed None` (or any changing integer) for non-deterministic results; default is `1337`.\n\n| Mesh                             | Point cloud                    | Background                           |\n|----------------------------------|--------------------------------|--------------------------------------|\n| ![mesh](examples/mesh_color.png) | ![pcd](examples/pcd_color.png) | ![mesh_depth](examples/bg_color.png) |\n| `--color bright_blue`            | `--pcd True` `--color cool`         | `--bg-color pale_turquoise`          |\n\n### Background\n\nBy default, the background is transparent. To change this, use the `--bg-color` option as shown above. Additionally,\nset `--transparent False` to render the backdrop object. To use HDRI images as backdrops, use `--backdrop path/to/hdri`.\nHDRIs can be obtained e.g. via `uv run blenderproc download haven path/to/save/dir`.\n\n| Backdrop                           | Colored backdrop                           | HDRI backdrop                               |\n|------------------------------------|--------------------------------------------|---------------------------------------------|\n| ![backdrop](examples/backdrop.png) | ![bd_color](examples/backdrop_colored.png) | ![hdri](examples/hdri.png)                  |\n| `--transparent False`              | `--transparent False` `--bg-color pale_red`| `--transparent False` `--backdrop path/to/hdri` |\n\n## Light\n\nThe default light intensity for meshes is `bright` (`0.7`) and `very_bright` (`1.0`) for point clouds. Use a value\nbetween 0 and 1 or `very_dark`, `dark`, `medium`, `bright`, or `very_bright` to change the light intensity.\n\n| Very Dark                            | Dark                       | Medium                         |\n|--------------------------------------|----------------------------|--------------------------------|\n| ![very_dark](examples/very_dark.png) | ![dark](examples/dark.png) | ![medium](examples/medium.png) |\n| `--light very_dark`                  | `--light dark`             | `--light medium`               |\n\n### Shadow\n\nShadows are rendered by default. To disable them, use the `--shadow off` option. To make the shadow softer, use\n`--shadow soft` or `--shadow hard` for a harder shadow.\n\n| Soft shadow                       | Hard shadow                       | No shadow                           |\n|-----------------------------------|-----------------------------------|-------------------------------------|\n| ![soft](examples/shadow_soft.png) | ![hard](examples/shadow_hard.png) | ![no_shadow](examples/noshadow.png) |\n| `--shadow soft`                   | `--shadow hard`                   | `--shadow off`                        |\n\n### Shading\n\nThe default shading is `flat` for meshes. Use `--shade` to change mesh shading; point clouds are unaffected by this option.\n\n| Flat shading (default)     | Smooth shading                 | Auto-smooth shading               |\n|----------------------------|--------------------------------|-----------------------------------|\n| ![flat](examples/mesh.png) | ![smooth](examples/smooth.png) | ![auto](examples/auto-smooth.png) |\n|                            | `--shade smooth`               | `--shade auto`                    |\n\n### Wireframe\n\nTo render the object as a wireframe, use the `--wireframe` option (e.g. `--wireframe True` or `--wireframe red`).\nThe wireframe color can be changed using `--wireframe color` when `--keep-mesh` is specified.\n\n| Wireframe                            | Mesh + Wireframe                        | Mesh + Wireframe (Color)                            |\n|--------------------------------------|-----------------------------------------|-----------------------------------------------------|\n| ![wireframe](examples/wireframe.png) | ![wf_mesh](examples/wireframe_mesh.png) | ![wf_mesh_color](examples/wireframe_mesh_color.png) |\n| `--wireframe True`                        | `--wireframe True` `--keep-mesh`             | `--wireframe red` `--keep-mesh`                     |\n\n### Gravity\n\nObjects hover slightly above the ground by default. To change this, use the `--gravity` option to run quick physics\nsimulation to let the object fall to the ground before rendering.\n\n| Default                          | With gravity                     |\n|----------------------------------|----------------------------------|\n| ![no_gravity](examples/mesh.png) | ![gravity](examples/gravity.png) |\n|                                  | `--gravity`                      |\n\n### Animations\n\nTo create an animation, use the `--animate` option. Control length with `--frames` (default: `72`) and playback speed with `--fps` (default: `20`). To keep transparency, which is not supported by GIF, use `.mp4` as file extension.\n\n| Turn (default, loops)      | Tumble                         |\n|----------------------------|--------------------------------|\n| ![turn](examples/turn.gif) | ![tumble](examples/tumble.gif) |\n| `--animate turn`                | `--animate tumble`             |\n\n### Interactive 3D Visualization\n\nTo provide an interactive 3D visualization, use `--export path/to/mesh.glb` to export the object as a `.glb` file and\nuse\n\n```html\n\u003cscript type=\"module\" src=\"https://ajax.googleapis.com/ajax/libs/model-viewer/4.1.0/model-viewer.min.js\"\u003e\u003c/script\u003e\n\n\u003cstyle\u003e\nmodel-viewer {\n  width: auto;\n  height: 300px;\n  display: block;\n  margin-left: auto;\n  margin-right: auto;\n}\n\u003c/style\u003e\n\n\u003cmodel-viewer \n  src=\"path/to/mesh.glb\" \n  camera-controls tone-mapping=\"neutral\" \n  shadow-intensity=\"1\" \n  auto-rotate\u003e\n\u003c/model-viewer\u003e\n```\n\nin any HTML file (like the hosted [**GitHub** Pages site](https://hummat.github.io/bproc-pubvis) of this repository) to display the object.\n\n### Further Options\n\nSome additional useful options include:\n\n* `--roughness`: Change the roughness of the object. Meshes use `0.5` and point clouds `0.9` by default.\n* `--ao`: Apply ambient occlusion (_on_ for meshes, _off_ for point clouds by default)\n* `--fstop`: Enable depth of field with a given f-stop\n* `--keep-material`: Keep your custom material (only works for `.blend` files)\n* `--point-size`: Change the size of the points in the point cloud\n* `--point-shape`: Change the shape of the points in the point cloud (`sphere`, `cube`, `diamond`)\n* `--verbose`: Enable verbose logging during execution\n* `--seed`: Set a seed for the random number generator; use `None` to disable seeding.\n* `--subsample` / `--subsample-method {random,fps}`: Reduce point counts by a target number or fraction.\n* `--point-color`: Explicit point color when differing from mesh color.\n* `--bg-light`: Adjust background light intensity (default `0.15`).\n* `--look`, `--engine`, `--samples`, `--noise-threshold`, `--exposure`: Advanced render controls.\n* `--frames`, `--fps`: Animation length and playback speed.\n\nUse `uv run blenderproc run main.py` to see all available options and their descriptions.\n\n## Development\n\nThis repository uses [`uv`](https://docs.astral.sh/uv/) for dependency management and task running.\n\n```bash\n# Clone and set up\ngit clone https://github.com/hummat/bproc-pubvis.git\ncd bproc-pubvis\nmake deps          # runs uv sync --group dev + configures git hooks\n```\n\nAfter any code change, run the full tooling suite via `make check`, or individually:\n\n```bash\nuv run ruff format .   # Format\nuv run ruff check .    # Lint\nuv run pyright         # Type check\nuv run pytest          # Unit tests (set BPROC_INTEGRATION=1 for integration tests)\n```\n\nRe-run `make deps` only when you intentionally want to refresh dependencies.\n\nIntegration tests exercise the BlenderProc CLI end-to-end and are opt-in:\n\n```bash\nBPROC_INTEGRATION=1 uv run pytest tests/test_integration.py\n```\n\nTo regenerate the README gallery assets with your GPU/HDRI set-up, run the gallery suite (writes into `examples/` by\ndefault). This is **opt-in** and separate from the basic integration flag:\n\n```bash\nBPROC_INTEGRATION=1 BPROC_EXAMPLES=1 \\\nBPROC_HAVEN_DIR=/path/to/haven \\\nBPROC_EXAMPLES_OUT=examples \\\nuv run pytest tests/test_integration.py -k readme_gallery\n```\n\nOptional env knobs:\n- `BPROC_README_RES` (default `512`) to change render resolution\n- `BPROC_README_FRAMES` (default `72`) to change animation length\n\nSee `AGENTS.md` for contributor-focused details (tooling, PR expectations, and how to run integration tests safely).\n\n## Debugging\n\n`BlenderProc` supports visual debugging inside `Blender` using `uv run blenderproc debug` instead of `uv run blenderproc run`.\nAdding `--debug` will further disable rendering and only set up the scene.\n\n## Credits\n\n* [**BlenderProc 2**](https://github.com/DLR-RM/BlenderProc)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/6104887/137109535-275a2aa3-f5fd-4173-9d16-a9a9b86f66e7.gif\" alt=\"blenderproc\" width=\"auto\"\u003e\n\n* [**Blender**](https://www.blender.org)\n\n\u003cimg src=\"https://download.blender.org/branding/blender_logo_socket.png\" alt=\"blender\" width=\"auto\"\u003e\n\n* [**Zheng et al.: Locally Attentional SDF Diffusion for Controllable 3D Shape Generation**](https://zhengxinyang.github.io/projects/LAS-Diffusion.html): Mesh colors and look\n* [**Yang et al.: PointFlow: 3D Point Cloud Generation with Continuous Normalizing Flows**](https://www.guandaoyang.com/PointFlow): Point cloud color scheme and look\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhummat%2Fbproc-pubvis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhummat%2Fbproc-pubvis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhummat%2Fbproc-pubvis/lists"}