picopie 0.4.0

A Pythonic binding for the PicoGK computational-geometry kernel

PicoPie

A Pythonic binding for PicoGK — LEAP 71's compact computational-geometry kernel for engineering (voxel / level-set modeling on OpenVDB).

PicoPie binds the same native runtime the official C# library uses — so you get identical geometry and performance — then wraps it in an idiomatic, NumPy-friendly Python API. No .NET, no compiler, no system libraries: just pip install picopie.

import picogk
from picogk import Voxels

picogk.init(voxel_size_mm=0.2)

body = Voxels.sphere(radius=10)
hole = Voxels.sphere(center=(6, 0, 0), radius=6)
part = body - hole          # boolean subtract → new Voxels
part.shell_(1.0)            # hollow to a 1 mm wall (in place)

vol, bbox = part.calculate_properties()
print(f"{vol:.1f} mm³")
part.to_mesh().save_stl("part.stl")

A gyroid-filled sphere built with picogk.shapes — see the gallery.

Install

pip install picopie            # core
pip install "picopie[viz]"     # + headless slice/mesh PNG helpers (Pillow, matplotlib)

or with uv:

uv add picopie

Wheels are self-contained — the native runtime (OpenVDB 13, PicoGK 26.2) and all its C++ deps are bundled. Prebuilt for CPython 3.10–3.13 on Linux (manylinux x86-64), macOS (Apple Silicon), and Windows (x64).

Documentation

• Tutorials — a leveled path: Novice (uv setup + install → shapes → booleans), Intermediate (implicit modeling, meshes/files, fields), Advanced (performance, reliability, viewer), and Shapes (the parametric ShapeKernel layer)
• Gallery — rendered parametric-shape examples
• QuickLearn — the whole API in one annotated file (learn-x-in-y-minutes style)
• API reference · docs build with mkdocs build (pip install -e ".[docs]")

Features

• Voxels — primitives (sphere, capsule), booleans (+ - &), offsets, shell_ (hollow), implicit SDF modeling, and queries (is_inside, closest_point, surface_normal, ray_cast, calculate_properties).
• Mesh — from voxels (marching cubes), NumPy vertices/triangles, STL/OBJ import and export.
• Lattice (beams + spheres), ScalarField / VectorField (bulk set_many/get_many), Metadata, PolyLine.
• File I/O — save_vdb / load_vdb round-trips voxels + fields (OpenVDB).
• Headless viz ([viz]) — save_slice_png, save_slice_sheet, mesh_preview.
• Interactive viewer — picogk.show(part) (GLFW/OpenGL, orbit camera) and render_png(part, "out.png") for offscreen renders.
• Web viewer ([web]) — picogk.web.show(part) renders inline in Jupyter/VS Code/Colab via three.js (works over SSH, where the desktop viewer can't), and picogk.web.export_html(part, "v.html") writes a self-contained interactive file.
• Parametric shapes (picogk.shapes) — a Pythonic port of LEAP 71's ShapeKernel: Sphere/Box/ Cylinder/Cone/Ring/Lens/Pipe/PipeSegment/Revolve/LogoBox defined by local frames + modulations, spines/splines, lattices, implicit SDFs (gyroid, super-ellipsoid, …), measurement (volume/area/CoG/inertia), and colour/painter helpers — parity-tested vs C# ShapeKernel. See the Shapes tutorials and gallery.
• Fast path — a compiled _fastloop extension (~13–28× faster bulk mesh/field transfer) with automatic pure-Python fallback.

Reliability

PicoPie is validated against the reference and hardened well beyond a naive binding:

• Parity-tested vs C# PicoGK on the same runtime — volumes, dims, mesh counts/bbox, and geometric queries match to float precision.
• Never aborts — the native runtime is patched so a C++/OpenVDB error surfaces as a catchable PicoGKError instead of killing the process; non-finite inputs are rejected up front. Verified against thousands of fuzzed inputs.
• Reproducible & auditable — every upstream dependency is version-pinned; builds ship an SBOM (sbom.cdx.json) and hash-pinned build deps.
• Green CI across Linux/macOS/Windows; mypy + ruff clean; ~190 tests.

Development

git clone https://github.com/Borderliner/PicoPie && cd PicoPie
python -m venv .venv && source .venv/bin/activate
scripts/build_runtime.sh         # build + stage the native runtime (see below)
pip install -e ".[dev]"
pytest

Building the native runtime (Linux) needs system deps:

sudo apt-get install -y --no-install-recommends \
  libboost-all-dev libblosc-dev libtbb-dev extra-cmake-modules \
  xorg-dev mesa-common-dev libgl1-mesa-dev ninja-build cmake g++ git
scripts/build_runtime.sh

PicoPie locates the runtime automatically: bundled in the wheel (picogk/_lib/), else under native/, else via $PICOGK_RUNTIME (full path to the shared library). Cross-platform wheels are built by cibuildwheel in .github/workflows/wheels.yml.

See ROADMAP.md for the (now-complete) phase history and PLAN.md for the architecture rationale.

License

Apache-2.0, matching upstream PicoGK / PicoGKRuntime. Ported by Mohammadreza Hajianpour and Vish Vadlamani.