Metadata-Version: 2.4
Name: picopie
Version: 0.5.0
Summary: A Pythonic binding for the PicoGK computational-geometry kernel
Author-email: Mohammadreza Hajianpour <hajianpour.mr@gmail.com>, Vish Vadlamani <global.takeover7@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Borderliner/PicoPie
Project-URL: Repository, https://github.com/Borderliner/PicoPie
Project-URL: Issues, https://github.com/Borderliner/PicoPie/issues
Project-URL: PicoGK (upstream), https://github.com/leap71/PicoGK
Keywords: geometry,voxels,openvdb,implicit,cad,additive-manufacturing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.23
Provides-Extra: viz
Requires-Dist: pillow>=9; extra == "viz"
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: web
Requires-Dist: anywidget>=0.9; extra == "web"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: picopie[viz]; extra == "dev"
Requires-Dist: picopie[web]; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Dynamic: license-file

# PicoPie

A **Pythonic binding for [PicoGK](https://github.com/leap71/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`.

> ⚠️ **Unofficial & community-maintained.** PicoPie is an independent project —
> **not** affiliated with, endorsed by, or supported by LEAP 71. It binds the
> open-source PicoGK runtime, but the API, packaging, and namespace (`picopie`,
> not `picogk`) are ours. Please file issues **here**, not with the PicoGK team.

```python
import picopie
from picopie import Voxels

picopie.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")
```

[![Parametric shapes gallery](docs/images/gallery/gyroid_sphere.png)](docs/gallery.md)

*A gyroid-filled sphere built with `picopie.shapes` — see the [gallery](docs/gallery.md).*

## Install

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

or with [uv](https://docs.astral.sh/uv/):

```bash
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](docs/tutorials/novice/01-setup.md) (uv setup + install → shapes → booleans),
  [Intermediate](docs/tutorials/intermediate/01-implicit-modeling.md) (implicit modeling,
  meshes/files, fields), [Advanced](docs/tutorials/advanced/01-performance.md)
  (performance, reliability, viewer), and
  [Shapes](docs/tutorials/shapes/01-parametric-shapes.md) (the parametric ShapeKernel layer)
- **[Gallery](docs/gallery.md)** — rendered parametric-shape examples
- **[QuickLearn](docs/tutorials/QuickLearn.md)** — the whole API in one annotated file
  (learn-x-in-y-minutes style)
- **[API reference](docs/api.md)** · 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** — `picopie.show(part)` (GLFW/OpenGL, orbit camera) and
  `render_png(part, "out.png")` for offscreen renders.
- **Web viewer** (`[web]`) — `picopie.web.show(part)` renders inline in Jupyter/VS
  Code/Colab via three.js (works over SSH, where the desktop viewer can't), and
  `picopie.web.export_html(part, "v.html")` writes a self-contained interactive file.
- **Parametric shapes** (`picopie.shapes`) — a Pythonic port of LEAP 71's
  [ShapeKernel](https://github.com/leap71/LEAP71_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](docs/tutorials/shapes/01-parametric-shapes.md) and [gallery](docs/gallery.md).
- **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 `PicoPieError` 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

```bash
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:

```bash
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 (`picopie/_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`](ROADMAP.md) for the (now-complete) phase history and
[`PLAN.md`](PLAN.md) for the architecture rationale.

## License

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