pardesline

[pardesline logo: wordmark with a point-cloud glyph]

pardesline: 3D computer vision and medical imaging datasets, algorithms and models for Python

Load 43 public 3D and medical datasets in one line, run 73 algorithms on point clouds, meshes and CT/MRI volumes with defaults that hold on real scans, hand the result to Open3D, PyVista or SimpleITK, or to an AI agent through MCP.

[PyPI version] [Python versions] [PyPI downloads per month] [CI status] [Test coverage] [Docs build] [OpenSSF Scorecard] [Documentation] [License Apache-2.0] [Citation file] [GitHub Discussions]

[Animated carousel of ten 3D vision and medical imaging pipelines built with pardesline: JEPA, DINOv3, ultrasound atlas transfer, Gaussian splats, 3D representations, atlas segmentation, PointNet, VAE anomaly detection, CT/MR registration, RANSAC + ICP]
_{Ten pipelines, one package: the showcase has the snippet, the expert skill and the MCP tool for each.}

30-second demo: dataset in, registration out

pip install "pardesline[all]"

import pardesline as plimport pyvista as pv
s = pl.load("rire_brain")[0]  # CT + MR T1 of one head (19 MB); the licence line is printed, never guessedmoved = s.ct.align(s.mr_t1)  # rigid registration: SimpleITK, Mattes mutual information, catalog defaultsprint(moved.transform["sub_transforms"][0]["rotation_deg"])  # [0.34, -0.35, -4.38] degrees
ct, mr = s.ct.to_pyvista(), moved.to_pyvista()  # the libraries you already use, one call awayp = pv.Plotter(shape=(1, 2))p.subplot(0, 0)p.add_mesh(ct.slice("z"), cmap="gray")p.add_text("CT (fixed)")p.subplot(0, 1)p.add_mesh(ct.slice("z"), cmap="gray")p.add_mesh(mr.slice("z"), cmap="magma", opacity=0.55)p.add_text("MR T1 registered onto the CT")p.show()

[Left: axial CT slice of the RIRE brain. Right: the same CT slice with the registered MR T1 overlaid in colour]

Measured cold on a laptop: 7.6 s download, 8.8 s registration, 21.5 s total. The script is examples/register_ct_mr_rire/run.py.

Why this exists

• Datasets are scattered and incompatible. The Decathlon is a tar on S3, TCIA is a REST API that returns zips of DICOM, KiTS is on Hugging Face, KITTI is a zip of headerless binaries. pardesline describes each one in a manifest (files, roles, labels, frame, units, licence, citation) and fetches lazily, by HTTP Range inside archives when it can, so one sample costs one sample.
• Nothing carries its meaning. A .bin is numbers until someone says (N, 4) float32, x y z reflectance, metres. A NIfTI label map is integers until someone says 1 = anterior. Manifests carry that; your own folders get it through pl.scan, which asks what it cannot know instead of guessing.
• Open3D, PyVista and SimpleITK do not talk to each other. One typed object (PointCloud, Mesh, Volume, LabelMap) converts between them, keeps frame, units, labels, licence and provenance, and exposes to_open3d(), to_pyvista(), to_sitk() when you want the library itself.
• Textbook defaults break on real scans. The ICP that converges on the tutorial fragments ends 32 degrees off on a noisy partial scan while reporting a 0.98 fitness. Every algorithm here runs behind one call with defaults tied to the data (voxel size from the bounding box, correspondence distances as multiples of it) and the sidecar records what was used. See Defaults that work on real data.
• Models do not plug into datasets. The expert skills and reference scripts (PointNet, DINOv3 features, JEPA, VAE, nnU-Net preparation) read any pardesline dataset. One-line access to pretrained models through the same manifest pattern is the next step on the roadmap.

Install

pip install pardesline                 # core: catalog, object model, datasets, CLI (no native libraries)pip install "pardesline[local]"        # + Open3D, PyVista, SciPy, scikit-image: point clouds, meshes, LiDAR, SDFpip install "pardesline[medical]"      # + SimpleITK: volumes, DICOM series, registration, segmentationpip install "pardesline[hf]"           # + huggingface_hub: datasets on the Hubpip install "pardesline[mcp]"          # + mcp: the local server for AI agentspip install "pardesline[all]"          # everything above

[local] needs Open3D wheels: 0.20 covers Python 3.10 – 3.13, 0.19 covers 3.10 – 3.12. pardesline 0.2.0 on PyPI pins Open3D below 0.20, so on Python 3.13 use 3.12 or install from main until 0.3.0 ships. Conda users: conda create -n pl python=3.12 && pip install "pardesline[all]" (Open3D and SimpleITK come from PyPI). Troubleshooting: docs/running-modes.md.

📦 Datasets

One loader for every source. Files are fetched on access and verified; the licence and the citation travel with the data; ds.describe() says what each role is, in which frame and units, and what the labels mean.

ds = pl.load("totalsegmentator_ct")  # 1 228 CTs, 117 structures, 23 GB zip on Zenodo: indexed with 14 MBct = ds.take(1)[0].ct  # one 50 MB volume fetched by HTTP Range, nothing elseds = pl.load(    "hf://neheller/KiTS-Challenge-Imaging")  # any Hugging Face repo: a manifest is drafted and confirmedds = pl.load("tcia://Pancreas-CT")  # any public TCIA collection: DICOM series as foldersds = pl.scan("/data/my_study")  # your folder: drafts a manifest, asks for units / labels / licence

Medical (35)

General 3D (8)

"Size" is the whole source; one sample costs its own size. "See source" means the data owner states terms outside a standard licence; ds.describe() prints them and the loader warns. Not bundled, and why: BraTS (Synapse data-use agreement), ModelNet, ShapeNet and ScanNet (registration-gated downloads); they are on the Datasets wanted list.

What standardization and the manifest give you: every role is typed (volume, labels, mesh, points, splat, image, transform), with frame (LPS, sensor, Y-up), units (mm, m), label names, raw-array layouts, licence, citation and provenance; label maps become exact surfaces in world coordinates, DICOM series become one volume, .npy/.bin become point clouds; ds.export(folder) writes standard PLY / MetaImage files with sidecars; ds.split(by="patient") never leaks a patient across splits. Add a dataset: CONTRIBUTING.md and docs/datasets.md.

🧠 Algorithms & models

Every row is a public capability of the package today. "Works on" names the object types from the table above. "Validated on" names the bundled data an example or test exercised; a blank cell means the method is covered by generated-data tests only.

Classical algorithms (73 methods in 19 catalog modules; pl.describe("module.method") prints every parameter with its range)

Deep-learning models (reference implementations and expert guides; no weights are shipped and there is no inference API yet. The direction: one-line pretrained model access through the same manifest and loader pattern as datasets, see the model registry tracking issue.)

Metrics & evaluation

Defaults that work on real data

Same task, same two clouds: the Stanford bunny sampled to 20 000 points, and a second "scan" rotated by 35°, trimmed to 70 % overlap and jittered with 0.5 % noise of the bounding-box diagonal. Left, Open3D's registration_icp the way the tutorial calls it; right, target.align(moving).

reg = o3d.pipelines.registration.registration_icp(    moving, target, 0.02, np.eye(4), TransformationEstimationPointToPoint())

aligned = target.align(moving)

What the one call sets, and why:

• voxel_size = 0 → 1.3 % of the bounding-box diagonal: the feature scale follows the object, not a hard-coded 0.05 m that is wrong for a 15 cm bunny and for a 15 m facade alike.
• distance_threshold_factor = 1.5 × voxel: RANSAC accepts a correspondence within one and a half cells; tighter rejects true matches on noisy scans, looser lets outliers in.
• RANSAC on FPFH first, ICP second: ICP alone is a local optimiser and needs a start within a few degrees; a 35° offset is outside its basin, which is why the textbook call stops where it started.
• icp_estimation_method = point_to_plane, icp_threshold_factor = 1.5 × voxel then refine_threshold_factor = 0.4 × voxel: coarse to fine, so the last iterations are not pulled by the 30 % of points that have no counterpart.
• Every value is in the sidecar aligned.provenance[-1]["params"], and pl.describe("registration.ransac_icp_pipeline") prints the ranges to override them.

Numbers come from examples/icp_registration_bunny/run.py (result.json is committed next to the images). The written proof for every algorithm family, failure mode by failure mode, is the docs page Why our defaults work.

Validated on real cases

These run on public data that stands in for the industrial and medical scans the defaults were tuned on. Real cases from users are collected in examples/real_cases/: a template and a tracking issue, so that every claim on this page stays reproducible.

How it compares

pardesline is the dataset layer and the domain-level API on top of these libraries, not a replacement: it calls Open3D, PyVista, VTK and SimpleITK and hands you their objects. Each cell is checked against the project's own documentation; corrections are welcome as issues.

Full page with the sources of each cell: docs comparison.

Examples gallery

Each folder is one self-contained script that downloads what it needs, runs, and writes its images next to itself. Titles follow <algorithm or model> on <dataset>. Run any of them with python examples/<folder>/run.py.

Also: Dice / HD95 between three radiologists on the liver tumour CT (0.82 to 0.85 Dice, 2.5 mm HD95: the inter-observer ceiling). The PyTorch examples need pip install torch (CPU is enough); DINOv3 weights need the licence accepted on the Hub, DINOv2 does not. Index and expected runtimes: examples/README.md.

🤖 MCP: give it to an AI agent

pip install "pardesline[mcp]"claude mcp add pardesline -- pardesline mcp        # Claude Code; Claude Desktop, Cursor, Gemini CLI, Codex: {"command": "pardesline", "args": ["mcp"]}

The server exposes the datasets, the algorithms, the object model and the twenty skills as tools: list_datasets, describe_dataset, list_samples, load_sample, scan_dataset, confirm_dataset, export_dataset, list_methods, describe_method, run_method, describe_object, to_mesh, list_skills, get_skill. An agent can browse the catalog, fetch one sample, run a pipeline, read the expert guide for the method it is about to use, and export standard files. Questions the package will not guess (licence, units, array layout) come back as JSON for the agent to relay to the human. No account, nothing leaves the machine. Client configurations and the full contract: docs/mcp.md.

Roadmap

Vote with 👍 on the tracking issue; comment with your dataset, model or use case.

• Model registry: one-line access to pretrained 3D and medical models (DINOv3, SAM-3D-style segmenters, JEPA encoders, PointNet, segmentation nets) through a model manifest (source, weights URI, licence, input type, task, memory needs, provenance) and pl.load_model(...) / pl.run(model, dataset), the same pattern as datasets. Tracking issue
• Gaussian splats as a first-class kind (Splat: load, render, convert to points, metrics). Tracking issue
• More datasets: BraTS (behind the user's Synapse credentials), VerSe 2020, the remaining public TCIA collections, ModelNet / ShapeNet / ScanNet once their gating can be honoured. Datasets wanted
• Models wanted: model manifests contributors can write before the runner exists. Models wanted
• Benchmarks: package defaults vs upstream defaults on the bundled data, numbers regenerated by CI. Tracking issue
• A pardesline organisation on Hugging Face mirroring the permissive datasets with pip install pardesline as the documented loader. Tracking issue
• Deformable registration and TotalSegmentator-class segmentation behind the same calls (align(mode="deformable"), segment(model=...)). Tracking issue

Community and contributing

• Questions and show-and-tell: GitHub Discussions.
• Bugs and requests: issues, with templates for bugs, features, dataset requests and algorithm or model requests.
• First contribution: good first issues, most of them "add dataset X" or "add algorithm Y" with a template to copy.
• How to set up, test, add a dataset, an algorithm or a model: CONTRIBUTING.md. Code of conduct: CODE_OF_CONDUCT.md. Security: SECURITY.md.

Citation

If pardesline helps your research, cite it (CITATION.cff, also behind the "Cite this repository" button):

@software{tabet_pardesline_2026,  author  = {Tabet, Jonathan},  title   = {pardesline: 3D vision and medical imaging in one Python package},  year    = {2026},  version = {0.2.0},  url     = {https://github.com/pardesline/pardesline},  license = {Apache-2.0}}

Cite the datasets you use as well: ds.citation returns the reference the data owner asks for.

Acknowledgements and licence

pardesline stands on Open3D, PyVista and VTK, SimpleITK, NumPy, SciPy, scikit-image, pycpd, httpx, pydantic, loguru, huggingface_hub and the MCP Python SDK. The datasets belong to their authors and institutions; every manifest carries the citation they ask for and the licence they state.

Apache License 2.0 for the package; see LICENSE and NOTICE. Datasets keep their own licences: ds.describe() prints them.

[Star history chart of pardesline/pardesline]