Metadata-Version: 2.4
Name: inv2dcm
Version: 1.0.0
Summary: Convert InVivo .inv dental CBCT volumes to Enhanced CT DICOM
Author: mrexodia
License-Expression: BSL-1.0
Project-URL: Homepage, https://github.com/mrexodia/inv2dcm
Project-URL: Repository, https://github.com/mrexodia/inv2dcm
Project-URL: Issues, https://github.com/mrexodia/inv2dcm/issues
Keywords: inv,dicom,cbct,cone beam ct,dental imaging,pydicom,enhanced ct,jpeg 2000
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: imagecodecs>=2024.12.30
Requires-Dist: numpy>=2.0.0
Requires-Dist: pydicom>=3.0.0
Dynamic: license-file

# inv2dcm

**inv2dcm** is a Python package and CLI for converting **InVivo `.inv` files** into **Enhanced CT DICOM (`.dcm`)**.

It is built for **dental CBCT / cone beam CT** data associated with **InVivoDentalViewer**, **CliniView**, and **Anatomage** workflows, including scans from systems such as **Instrumentarium Dental ORTHOPANTOMOGRAPH OP 3D Pro**.

The `.inv` files handled here use the **`INVFile`** XML container format, with an `AppendedData` payload containing JPEG 2000-compressed voxel data.

If you are searching for an **INV to DICOM converter**, **InVivo INV file reader**, **dental CBCT to DICOM tool**, **cone beam CT to pydicom**, or a way to convert **`.inv` to 3D Slicer / VolView compatible DICOM**, this package is intended for that use case.

## Features

- Converts proprietary **`.inv`** volume files to **Enhanced CT DICOM**
- Outputs a **single multi-frame DICOM file**
- Reads scan metadata from the INV XML header
- Decodes embedded **JPEG 2000 codestreams** in pure Python via `imagecodecs`
- Produces output readable by:
  - `pydicom`
  - **3D Slicer**
  - **VolView**
  - other DICOM-capable medical imaging tools
- Includes both a Python library API and a CLI command: `inv2dcm`

## Installation

### From source

```bash
pip install .
```

### Development install

```bash
pip install -e .
```

## CLI usage

After installation, the console script is available as:

```bash
inv2dcm
```

### Convert a file

```bash
inv2dcm scan.inv
```

This writes `<input-stem>.dcm` next to the source file.

### Convert to a specific output path

```bash
inv2dcm scan.inv output/scan.dcm
```

### Control DICOM window metadata

```bash
inv2dcm scan.inv output/scan.dcm --window auto
```

Available modes:

- `auto` — derive a sane window center/width from the volume data
- `source` — preserve the source INV window metadata
- `none` — omit DICOM window center/width metadata

## Python library usage

`inv2dcm` is importable as a normal Python library, so it is suitable for publishing on **PyPI** and embedding in larger imaging workflows.

### Simple conversion

```python
from pathlib import Path
from inv2dcm import convert_inv_to_dicom

convert_inv_to_dicom(Path("scan.inv"), Path("scan.dcm"), window_mode="auto")
```

### Inspect decoded metadata and volume data

```python
from pathlib import Path
from inv2dcm import load_inv

inv = load_inv(Path("scan.inv"))
print(inv.metadata)
print(inv.volume.shape)
```

### Build the `pydicom` dataset yourself

```python
from pathlib import Path
from inv2dcm import build_enhanced_ct, load_inv

inv = load_inv(Path("scan.inv"))
ds = build_enhanced_ct(inv, Path("scan.dcm"))
print(ds.SOPClassUID)
print(ds.NumberOfFrames)
```

### Public API

- `load_inv(path)`
- `build_enhanced_ct(inv, output_path, window_mode="auto")`
- `convert_inv_to_dicom(input_path, output_path, window_mode="auto")`

## Verify with pydicom

```python
import pydicom

ds = pydicom.dcmread("scan.dcm")
print(ds.NumberOfFrames)
print(ds.Rows, ds.Columns)
print(ds.pixel_array.shape)
```

## View the converted DICOM in the browser

You can drag the generated `.dcm` file directly into **VolView**:

- https://volview.kitware.app/

This is a convenient way to inspect the converted dental CBCT volume in the browser without installing a desktop viewer.

## What kind of INV files are supported?

This project targets **InVivo dental CBCT `.inv` files** using the **`INVFile`** container format.

In practice, that means files with:

- an XML document rooted at `INVFile`
- bytes that begin with `<INVFile`
- an `AppendedData` block
- JPEG 2000 codestream containers storing the voxel data

That matches the structure documented by reverse-engineering work on InVivo / CliniView / Anatomage-related CBCT archives.

## Reverse-engineering references

This package was informed by prior work on the InVivo / CliniView `.inv` format and related dental CBCT tooling:

- holland.sh — **Digital CBCT scans**: https://holland.sh/post/digital-cbct-scans/
- InvivoConvert: https://github.com/AstrisCantCode/InvivoConvert
- InvivoExtractor: https://github.com/Bostwickenator/InvivoExtractor
- Reverse engineering my head: https://dev-with-alex.blogspot.com/2018/03/reverse-engineering-my-head.html

## Output format

The generated DICOM file uses:

- **SOP Class**: Enhanced CT Image Storage
- **Transfer Syntax**: Explicit VR Little Endian
- **Photometric Interpretation**: `MONOCHROME2`
- **Multi-frame volume storage** for easy loading in Python and modern viewers

## Why this package exists

The **`.inv`** format is awkward to use in standard Python medical imaging workflows. `inv2dcm` converts proprietary **InVivo CBCT** data into standard **DICOM** so it can be opened with **pydicom**, reviewed in **3D Slicer**, or inspected in **VolView**.

## Development

The CLI entry point is:

- `inv2dcm` → `inv2dcm.py`

You can also run it directly during development:

```bash
python inv2dcm.py scan.inv scan.dcm
```

## Keywords

INV to DICOM, InVivo INV converter, INVFile parser, dental CBCT DICOM converter, cone beam CT DICOM, JPEG 2000 medical imaging, pydicom INV import, InVivoDentalViewer export, CliniView INV parser, Anatomage InVivo, VolView DICOM viewer.
