Metadata-Version: 2.1
Name: polyxios
Version: 0.2.0
License: BSD 3-Clause License
         
         Copyright (c) 2026, fury-gl
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         1. Redistributions of source code must retain the above copyright notice, this
            list of conditions and the following disclaimer.
         
         2. Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
         
         3. Neither the name of the copyright holder nor the names of its
            contributors may be used to endorse or promote products derived from
            this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: cython>=3.0; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: spin; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: codespell; extra == "dev"
Provides-Extra: doc
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: numpydoc; extra == "doc"
Requires-Dist: sphinx-gallery; extra == "doc"
Requires-Dist: pydata-sphinx-theme; extra == "doc"
Description-Content-Type: text/markdown

# polyxios

**Fast, clean mesh I/O for Python.** Read and write 3D mesh files in one line - no hidden surprises, no silent data corruption.

---

## Install

```bash
pip install polyxios
```

---

## Usage

```python
import polyxios as px

# Read any supported format
mesh = px.read("brain.vtk")

# Inspect
print(mesh.vertices.shape)      # (n_verts, 3)
print(len(mesh.element_types))  # number of elements

# Write to a different format
px.write(mesh, "brain.ply")
px.write(mesh, "brain.vtp")
```

Need binary output or format-specific options?

```python
px.write(mesh, "brain.vtk", binary=True)
px.write(mesh, "brain.ply", binary=True, endian="little")
```

---

## Lazy loading - work with large files without filling RAM

For large meshes (gigabytes of binary data), pass `lazy=True`. polyxios
memory-maps the file and only loads the pages you actually touch - the rest
stays on disk until needed.

```python
# File is opened but data is not loaded into RAM yet
mesh = px.read("huge_brain.vtk", lazy=True)

# Only the vertices are pulled from disk here
first_vertex = mesh.vertices[0]

# Element connectivity is still on disk until you access it
```

Lazy loading is supported for binary `.vtk` and `.ply` files. ASCII formats
load eagerly (the whole file must be parsed to extract values).

---

## Supported formats

| Format | Extension | Read | Write | Lazy load |
|--------|-----------|------|-------|-----------|
| VTK Legacy | `.vtk` | ✓ | ✓ | binary only |
| VTK RectilinearGrid | `.vtr` | ✓ | ✓ | - |
| VTK PolyData | `.vtp` | ✓ | ✓ | - |
| Wavefront OBJ | `.obj` | ✓ | ✓ | - |
| Stanford PLY | `.ply` | ✓ | ✓ | binary only |

**5 formats supported** - more coming via the plugin system.

---

## Transforms

```python
from polyxios.transforms import pipeline, merge, filter_element_type, remove_orphan_vertices

# Compose transforms into a single function
clean = pipeline(
    filter_element_type(keep="triangle"),
    remove_orphan_vertices,
)
result = clean(mesh)

# Merge two meshes into one
combined = merge(mesh_a, mesh_b)
```

---

## Add your own format

Any third-party package can teach polyxios to read and write a new format -
no fork required, no pull request needed.

**Step 1 - write a codec** (two functions, nothing more):

```python
# mypackage/stl_codec.py
from polyxios._registry import Codec
from polyxios._types import PolyData

def read(path, *, lazy=False) -> PolyData:
    ...

def write(poly: PolyData, path, **opts) -> None:
    ...

def register():
    return ".stl", Codec(read, write)
```

**Step 2 - declare an entry point** in your `pyproject.toml`:

```toml
[project.entry-points."polyxios.codecs"]
stl = "mypackage.stl_codec:register"
```

After `pip install mypackage`, polyxios picks up `.stl` automatically -
no configuration, no restart needed:

```python
mesh = px.read("model.stl")   # works out of the box
```

---

## Contributing / Development

Clone the repo, then use [spin](https://github.com/scientific-python/spin) to
manage the development workflow:

```bash
pip install spin
spin setup       # add upstream remote + install dev deps (libomp on macOS)
spin install     # build Cython extensions and install
spin install -e  # editable install (source changes reflected immediately)
```

| Command | Description |
|---------|-------------|
| `spin setup` | First-time setup: upstream remote, dev deps, OpenMP on macOS |
| `spin build` | Build with Meson/ninja |
| `spin install` | Regular install (compiled) |
| `spin install -e` | Editable install for development |
| `spin test` | Run the full test suite |
| `spin test -k <pattern>` | Run tests matching a name pattern |
| `spin lint` | ruff linter + formatter check + codespell |
| `spin lint --fix` | Auto-fix lint and formatting issues |
| `spin docs` | Build Sphinx documentation |
| `spin docs --clean` | Wipe `_build/` before building |
| `spin docs --open` | Build and open docs in the browser |
| `spin clean` | Remove build artifacts and `__pycache__` |
| `spin release <version>` | Cut a release: bump version, tag, push, start next dev cycle |

See [`docs/contributing.rst`](docs/contributing.rst) for commit message
conventions and the full contributor guide.
For the full release workflow see [`docs/development.rst`](docs/development.rst).

---

## Why polyxios?

- **No silent data corruption** - large mesh indices raise an error instead of truncating
- **All element groups preserved** - a face belonging to multiple tags stays in all of them
- **Safe on untrusted files** - header counts validated before any memory allocation
- **Memory-efficient** - lazy mmap loading for large binary files
- **Works without a compiler** - pure Python fallbacks included; Cython hot-paths optional

---

## License

See [LICENSE](LICENSE).
