Skip to main content

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

pip install polyxios

Usage

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?

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

Command Line Interface (pxios)

polyxios comes with a command-line interface pxios to quickly fetch, list, convert, and visualize 3D models.

Subcommands

--verbose can be given on either side of the subcommand (e.g. pxios --verbose fetch bunny.obj or pxios fetch bunny.obj --verbose) to print debug logs and full tracebacks when a command fails.

  • pxios list: Lists all available remote or cached files, or registered formats. The three listing modes below are mutually exclusive.
    • --local: Lists locally cached files (can filter by optional extension argument, e.g. pxios list obj --local).
    • --extensions / --formats: Lists all formats and extensions available in the remote catalog.
    • --codecs: Lists all formats supported by polyxios codecs.
  • pxios fetch <filename|extension>: Downloads and caches a single model file (e.g., bunny.obj) or every model catalogued for an extension (e.g., obj or .obj).
  • pxios convert <input_file> <output_file>: Converts a model file from one format to another directly in a single process.
  • pxios viz <filename>: Visualizes a local or cached model file using the FURY library.
    • --lines: Render line elements using actor.line instead of rendering as a surface/point cloud.
    • --points: Render strictly as a point cloud.
# List all fetchable remote models
pxios list

# Fetch a single model
pxios fetch bunny.obj

# Fetch every model catalogued for an extension
pxios fetch vtk

# Convert a mesh file
pxios convert bunny.obj bunny.vtk

# Visualize a model
pxios viz bunny.obj

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.

# 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, .ply, and .stl files. ASCII formats load eagerly (the whole file must be parsed to extract values). Binary STL lazy mode skips vertex deduplication - vertices are returned as-is (3 per triangle), avoiding the extra pass over the data.


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
STL .stl binary only
OFF .off ASCII + big-endian binary, ST/C/N variants → vertex/face attrs
Abaqus .inp -
AVS-UCD .avs -
Medit binary .meshb binary only
DOLFIN/FEniCS XML .xml -
FLAC3D .f3grid zones + faces, groups → element tags
Gmsh .msh ✓ (v2) ASCII v2 + v4.1, physical groups → element tags
Nastran .bdf .nas .fem free/small/large field read, free-field write with large-field GRID on request; .dat via fmt=".bdf"
Tecplot ASCII .tec FE zone, POINT + BLOCK packing, solution variables → vertex attrs; .dat via fmt=".tec"
SU2 .su2 ASCII, VTK element codes, boundary markers → element tags
TetGen .ele+.node paired files, 1-/0-based indices, boundary markers → vertex tags, region attrs
UGRID (AFLR) .ugrid ASCII, tri/quad surface + tet/pyramid/prism/hex volume, boundary tags → element tags
Netgen .vol ASCII, points/edges/faces/cells incl. quadratic, bcnr/matnr + names → element tags
Well-Known Text .wkt 2D padded to z=0, holes → element attrs, EWKT SRID dropped

20 formats supported - more coming via the plugin system.


Transforms

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):

# mypackage/abc_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 ".abc", Codec(read, write)

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

[project.entry-points."polyxios.codecs"]
abc = "mypackage.abc_codec:register"

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

mesh = px.read("model.abc")   # works out of the box

Contributing / Development

Clone the repo, then use spin to manage the development workflow:

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 for commit message conventions and the full contributor guide. For the full release workflow see 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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

polyxios-0.3.0.tar.gz (345.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

polyxios-0.3.0-cp313-cp313-win_amd64.whl (690.4 kB view details)

Uploaded CPython 3.13Windows x86-64

polyxios-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (545.3 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

polyxios-0.3.0-cp313-cp313-macosx_11_0_arm64.whl (377.0 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

polyxios-0.3.0-cp312-cp312-win_amd64.whl (690.5 kB view details)

Uploaded CPython 3.12Windows x86-64

polyxios-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (546.1 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

polyxios-0.3.0-cp312-cp312-macosx_11_0_arm64.whl (378.6 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

polyxios-0.3.0-cp311-cp311-win_amd64.whl (694.3 kB view details)

Uploaded CPython 3.11Windows x86-64

polyxios-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (549.4 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

polyxios-0.3.0-cp311-cp311-macosx_11_0_arm64.whl (378.1 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

File details

Details for the file polyxios-0.3.0.tar.gz.

File metadata

  • Download URL: polyxios-0.3.0.tar.gz
  • Upload date:
  • Size: 345.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for polyxios-0.3.0.tar.gz
Algorithm Hash digest
SHA256 b62b555be81e92a2724dfe5e979f0f10fb9b0af7d6907bd91bc47eb814e827bf
MD5 ce63eda13ee701d90b96d7718fbe763f
BLAKE2b-256 6dc0d000a03febab9c46729bbb601df0322c8faea9bc78556651dd86abecf81a

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0.tar.gz:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polyxios-0.3.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: polyxios-0.3.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 690.4 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for polyxios-0.3.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 8fb50f3e387dadddcbbdedd26ffaa5de9607312541542cdc8fe5c0de4eb7b37f
MD5 dabd13910b13d2a0b865da11d271da2e
BLAKE2b-256 633e38798a279dbe46c29289be2863a04d4bcc8c69e7cb6702d4835e54e5a7cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0-cp313-cp313-win_amd64.whl:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polyxios-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for polyxios-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 715df5e6ab184973b1484ee802708693b92c7e4838d3b70c68a8486a5a24bd12
MD5 35a42bc9e5110e1be4a288477708004f
BLAKE2b-256 11d3f5980de0eb50c3b2cedb0a06e48f64a4566c53871d3801501e480955bf62

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polyxios-0.3.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for polyxios-0.3.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0e38e6484b7a41e5adbfbe3d624b2037b787ba97691c8a81d976a278a82e84fb
MD5 71dcd6a030b81378dc6bbdb9c6803033
BLAKE2b-256 3e0ee21a93b04ace5ebae2ca3857817b3a831553f9ff636de72aae9bb88eb546

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polyxios-0.3.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: polyxios-0.3.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 690.5 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for polyxios-0.3.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 8ec9e912efbb4c3edabe50ebc964a3c7539d9c542f7e7deb524ecd36925a0eea
MD5 a9bad9b182d7accce45aeafed30400e9
BLAKE2b-256 25a77f6ee9f73bf59648b64294581b93cf594e23f23df9d58d1dfc0917faa683

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0-cp312-cp312-win_amd64.whl:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polyxios-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for polyxios-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 442da90b14902e8f3fed4afdb8fe87a6914f8cfdb0fff58322cfa93ba1e3936d
MD5 e06a5ef5dc46ab9925d3d53c4f525cd1
BLAKE2b-256 0d4e4c08b25ac54f90e06151aa1d0630b22299a582e57471e8e7be466fcada43

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polyxios-0.3.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for polyxios-0.3.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 61e22c6a0058e4b871c8eb4cd166013c3a1e59918d31327bf1ded866ec0e60d6
MD5 2ba8d33a1b0b736d22cb844e44b57b17
BLAKE2b-256 ccdd2a7b62254b913a122531c2cdc368dc964697f29230c30e66d52a8aaccbd9

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polyxios-0.3.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: polyxios-0.3.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 694.3 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for polyxios-0.3.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 2043b156c690b6fed60e49ea085cbc474636fe5f34bd4b9e93d230af2e16ce1f
MD5 1412f48c8d59090dd52c2035d3bada0e
BLAKE2b-256 f27c2d9b6db163f534d4ad22fe1171a29441d0ad755c4caddc09d684f206dead

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0-cp311-cp311-win_amd64.whl:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polyxios-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for polyxios-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 611d5fef07822820e973eccc7a777b1a1e9a636d370c88f4ef02e0b071ea391b
MD5 ef78b2fb7513c0595e997596cd425019
BLAKE2b-256 f462a9cb9bd43e28afd1de0b68bf98cf24dda0debe5ff0e0c160d35392beca50

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polyxios-0.3.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for polyxios-0.3.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c59a3107dc3aa5c12d4f025cf206601f7d921c6fbd117aa7bf6a0c51cb6b47f3
MD5 1ef0c81863ebd654ad3ffa0be86b5921
BLAKE2b-256 7f47a56f95069b57bb29860264601152587bb6f45671f56ec1e39b30ecb70d43

See more details on using hashes here.

Provenance

The following attestation bundles were made for polyxios-0.3.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on fury-gl/polyxios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.0 This release

10 files

0.2.0

10 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page