Metadata-Version: 2.4
Name: medics
Version: 202609151801
Summary: MedICS - Medical Image Computing Suite for visualization and analysis
Author-email: MedICS <medics.support@gmail.com>
License: Proprietary
Project-URL: Homepage, https://Medical-Image-Computing-Suite.github.io
Project-URL: Documentation, https://github.com/Medical-Image-Computing-Suite/Community/wiki
Project-URL: Issues, https://github.com/Medical-Image-Computing-Suite/Community/issues
Keywords: medical,imaging,visualization,analysis,dicom,itk,vtk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: PySide6>=6.8.2.1
Requires-Dist: pyopengl>=3.1.0
Requires-Dist: qtconsole>=5.5.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: opencv-python>=4.9.0
Requires-Dist: numpy<2.0.0,>=1.26.0
Requires-Dist: pyqtgraph>=0.13.0
Requires-Dist: scikit-image>=0.24.0
Requires-Dist: scipy>=1.13.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=2.1.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: pydicom>=2.4.0
Requires-Dist: h5py>=3.10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: natsort>=8.4.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: imageio>=2.34.0
Requires-Dist: imagecodecs>=2023.8.0
Requires-Dist: mat73>=0.65
Requires-Dist: astor>=0.8.1
Requires-Dist: medics-extension-sdk
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: napari>=0.6.6
Requires-Dist: tqdm>=4.66.0
Requires-Dist: setuptools>=65.0
Requires-Dist: click>=8.1.0
Requires-Dist: deepdiff>=5.9.0
Requires-Dist: requests>=2.31.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: hdf5plugin>=3.7.0
Requires-Dist: numba>=0.63.1
Requires-Dist: pyte>=0.8.0
Requires-Dist: ptyprocess>=0.7.0
Requires-Dist: pywinpty>=3.0.3; sys_platform == "win32"
Requires-Dist: asyncio>=4.0.0
Requires-Dist: autogen-agentchat>=0.7.5
Requires-Dist: autogen-ext[openai]>=0.7.5
Requires-Dist: cython>=3.2.4
Requires-Dist: mypy>=1.8.0
Requires-Dist: wheel>=0.47.0
Requires-Dist: build>=1.5.0
Requires-Dist: twine>=6.2.0
Requires-Dist: langchain>=1.3.14
Requires-Dist: langgraph>=1.2.10
Requires-Dist: langchain-openai>=1.4.1
Requires-Dist: langchain-anthropic>=1.5.4
Requires-Dist: langchain-google-genai>=4.3.2
Requires-Dist: langchain-ollama>=1.1.0
Requires-Dist: python-gdcm>=3.0.24
Requires-Dist: pylibjpeg>=2.1.0
Requires-Dist: pylibjpeg-libjpeg>=2.2.0
Requires-Dist: nibabel>=5.4.2
Requires-Dist: vtk>=9.3.0
Requires-Dist: deepseek-harness-sdk>=0.1.5rc1
Provides-Extra: models
Requires-Dist: onnxruntime>=1.17; extra == "models"
Provides-Extra: gpu
Requires-Dist: onnxruntime-gpu>=1.17; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: pylint>=3.0.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.2.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-applehelp>=1.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-devhelp>=1.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-htmlhelp>=2.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-qthelp>=1.0.0; extra == "docs"
Provides-Extra: all
Requires-Dist: medics[dev,docs,gpu,models]; extra == "all"
Dynamic: license-file

# MedICS — Medical Image Computing Suite

A cross-platform, modular platform for medical image visualization and analysis. MedICS combines a scientific Python workspace, built-in toolboxes, and a pip-installable extension system into one desktop application.

**Python 3.11+** · **Windows / macOS / Linux** · **Qt 6**

---

## Table of contents

- [MedICS — Medical Image Computing Suite](#medics--medical-image-computing-suite)
  - [Table of contents](#table-of-contents)
  - [Introduction](#introduction)
  - [Features](#features)
  - [The image model: `MedImage`](#the-image-model-medimage)
  - [Get started](#get-started)
    - [Requirements](#requirements)
    - [Install](#install)
    - [Launch](#launch)
    - [Basic workflow](#basic-workflow)
  - [Toolboxes](#toolboxes)
  - [Extensions](#extensions)
    - [Install an extension](#install-an-extension)
    - [Create an extension](#create-an-extension)
    - [Build and publish](#build-and-publish)
  - [License](#license)

---

## Introduction

MedICS (Medical Image Computing Suite) is a research-oriented desktop environment for loading, inspecting, and analyzing medical images. It is designed so that image I/O, interactive preview, Python scripting, and third-party tools share one workspace instead of living in separate applications.

Typical work happens in a single window:

- **File Explorer** for the current folder
- **Central tabs** for toolboxes (editor, importer, preview, extensions)
- **Variables** dock for the in-memory workspace
- **Bottom panel** for Jupyter, terminal, and logs

Data lives in a `DataDict` workspace and can be saved as a `.med` file (HDF5). Scripts in **PyEditor** and the embedded **Jupyter** console see the same variables.

Images in that workspace are represented by **`MedImage`** — the canonical medical-image data model described [below](#the-image-model-medimage) — which keeps pixels, geometry, metadata, annotations, and provenance together as one object while remaining compatible with the existing array-based formats.

---

## Features

| Area | What you get |
| --- | --- |
| **Image I/O** | DICOM (including JPEG 2000 / OCT series), TIFF stacks, NIfTI, HDF5 / `.med`, `.medimage` bundles, MATLAB `.mat`, PNG/JPEG, video (`.mp4`, `.avi`, `.mkv`, `.mov`, `.webm`, …), and other scientific formats via `FileIO` |
| **Image model** | `MedImage` — the canonical medical-image data model and data bus: named dimensions, physical geometry, typed metadata, annotations, AI predictions, and processing provenance |
| **Preview** | Double-click files in Explorer to inspect text, markdown, tables, 2-D images, and volumes (slice, window/level, transforms) |
| **Import** | Drag-and-drop importer with background loading and progress |
| **Python** | In-process Jupyter kernel plus a full editor (syntax highlighting, completions, terminal) |
| **Workspace** | Named variables, inspector, auto-save, load/save `.med` workspaces |
| **UI** | Dark and light QSS themes, draggable toolbar, dock layout, central tab workspace |
| **Extensions** | Discover pip packages (`medics.extensions` entry points) or drop-in folders; load, show, and unload without restarting the core app |

---

## The image model: `MedImage`

`MedImage` (`medics.core.medimage`) is the **canonical medical-image data model and data bus of MedICS**. It is the single interchange object shared by file I/O, preview, toolboxes, AI models, and the agent — so pixels, axis semantics, physical geometry, annotations, model outputs, and processing history travel together instead of being passed around as a bare array plus side-channel variables.

```python
from medics.core.medimage import MedImage, SpatialGeometry, ImageMetadata

image = MedImage.from_numpy(
    volume,                                  # numpy array
    dims=("bscan", "depth", "aline"),        # what each axis means
    geometry=SpatialGeometry(
        spatial_dims=("bscan", "depth", "aline"),
        spacing=(0.0468, 0.0039, 0.0117),    # mm per voxel
        coordinate_system="LPS",
        units=("mm", "mm", "mm"),
    ),
    metadata=ImageMetadata(modality="OCT"),
)
```

**Highlights**

- One class for 2D images, 3D volumes, 4D series, OCT and OCTA
- Explicit dimension semantics — index by axis name (`image.sel(z=slice(0, 10))`), not by convention
- Physical geometry: spacing, origin, direction, coordinate system
- Typed metadata plus PHI-aware patient/study/series context
- First-class annotations (masks, contours, retinal layer boundaries), AI predictions, and measurements
- Processing provenance recorded automatically by every transform
- Lazy backends (memmap, Dask, Torch) — pixels need not be materialised
- Native `.medimage` bundle, plus NumPy / NIfTI / DICOM / VTK adapters

**Backward compatible by design.** Existing code and files keep working. A compatibility bridge maps the legacy representations onto the canonical model — and back, losslessly:

| Legacy representation | Still works via |
| --------------------- | --------------- |
| Untyped `numpy.ndarray` volumes | `from_legacy_array` / `to_legacy_array` |
| Retinal-layer "curve dicts" | `apply_curve_dict` / `extract_curve_dict` |
| Integer label maps + colormaps | `label_map_to_annotation` / `annotation_to_label_map` |
| `permute` / `flip` orientation specs | `apply_legacy_orientation` |
| `.med` (HDF5) files and workspaces | transparent `MedImage` envelope in `FileIO` |

```python
from medics.core.medimage import from_legacy_array, to_legacy_array

image = from_legacy_array(volume, modality="OCT", oct=True)
assert (to_legacy_array(image) == volume).all()      # exact round-trip
```

The data model is **Qt-free** — NumPy is its only hard dependency — so it is usable from headless scripts, agent sandboxes, and generated code.

→ Guide and migration notes: [docs/medimage.md](docs/medimage.md)
→ Full API reference: [docs/api/core/medimage.md](docs/api/core/medimage.md)

---

## Get started

### Requirements

- Python **3.11** or later
- A supported OS: Windows, macOS, or Linux
- Scientific stack (NumPy, SciPy, scikit-image, pydicom, h5py, PySide6, and others) — installed automatically with the package

### Install

**From PyPi**

```bash
pip install medics
```

**Verify**

```bash
python -c "import medics; print(medics.__version__)"
medics --help
```

### Launch

```bash
medics
# or
python -m medics
```

Useful CLI commands:

```text
medics                              Start the application
medics --create-ext [NAME] [DIR]    Scaffold a new extension
medics --build-ext [OPTIONS]        Build an extension wheel
medics --version, -V                Print the installed version
medics --help                       Show CLI help
```

### Basic workflow

1. **Open a folder** — `File → Open Folder`, or use the folder button in the Explorer dock.
2. **Preview files** — Double-click a file in Explorer, or use **FilePreview**. Images, DICOM/NIfTI volumes, tables, markdown, and code open in tabs.
3. **Import data** — Open the **ImportData** toolbox (`Toolboxes` menu). Drag files or folders, or browse a DICOM series. Imported arrays appear in the Variables dock and in Jupyter.
4. **Analyze** — Write scripts in **PyEditor**, or run code in the **Jupyter** tab. Both share the workspace namespace.
5. **Save** — `File → Save Workspace` writes variables to a `.med` (HDF5) file. Auto-save can be enabled in settings.

---

## Toolboxes

Built-in toolboxes open as **tabs in the central widget**, not as dock panels. The Toolboxes menu controls which icons appear on the activity bar.

| Toolbox | Role |
| --- | --- |
| **PyEditor** | Python IDE: syntax highlighting, completions, AST outline, integrated terminal, run against the Jupyter kernel |
| **ImportData** | Unified importer for DICOM, NIfTI, TIFF/PNG/JPEG, video (MP4/AVI/MKV/MOV/WebM/…), HDF5, MAT, NumPy, CSV, and related formats; background workers with progress |
| **FilePreview** | Read-only preview of text, code, markdown, spreadsheets, 2-D images, and volumetric data (DICOM series, stacked TIFF, NIfTI, video frame stacks) |

Custom tools should be packaged as **extensions** rather than patched into `medics/toolboxes/`.

---

## Extensions

Extensions add UI, menus, and workspace tools without changing the MedICS core. They are discovered automatically from:

1. **pip packages** that declare a `medics.extensions` entry point (preferred)
2. **Filesystem drop-ins** under `medics/extensions/`

Discovery prefers entry points when the same ID exists in both places.

### Install an extension

```bash
pip install medics-ext-example
medics
```

Loaded extensions appear under the **Extensions** menu and, when `windowed` is true, can open a tab or window. Enable, disable, and inspect them from the extension manager dialog.

### Create an extension

```bash
medics --create-ext
# or with a name
medics --create-ext medics-ext-my-tool
```

This copies the bundled scaffold from `medics/extension_template/` and substitutes names. A typical layout:

```text
medics-ext-my-tool/
├── medics_ext_my_tool/
│   ├── __init__.py          # ExtensionInterface implementation
│   ├── extension.json       # Display metadata
│   └── ui/
│       └── main_widget.py   # Optional PySide6 widget
├── tests/
├── pyproject.toml
└── README.md
```

Every extension implements `ExtensionInterface`:

```python
def get_name(self) -> str: ...
def get_version(self) -> str: ...
def get_description(self) -> str: ...
def get_author(self) -> str: ...
def get_category(self) -> str: ...
def initialize(self, app_context) -> bool: ...
def cleanup(self) -> None: ...
def show_extension(self) -> None: ...
```

`initialize(app_context)` receives the running `MedICSMain` instance, so the extension can use the workspace, config, event bus, menus, and docks.

**`extension.json`**

```json
{
  "name": "My Tool",
  "version": "1.0.0",
  "description": "Does XYZ",
  "author": "Your Name",
  "category": "Image Analysis",
  "enabled": true,
  "windowed": true,
  "icon": null
}
```

**Entry point** (`pyproject.toml`)

```toml
[project.entry-points."medics.extensions"]
my_tool = "medics_ext_my_tool:MyToolExtension"
```

Lifecycle in short: discover → `initialize(app_context)` → menu/toolbar action → `show_extension()` → `cleanup()` on unload.

### Build and publish

Run from the extension project directory:

```bash
medics --build-ext                 # plain Python wheel (default)
medics --build-ext --protect       # Cython-compiled, source-stripped
medics --build-ext -p              # same as --protect
medics --build-ext --upload        # build, then upload to PyPI
medics --build-ext --upload --test-pypi
```

Full API and publishing notes: [docs/extension-system.md](docs/extension-system.md) and [medics/extension_template/docs/DEVELOPER_GUIDE.md](medics/extension_template/docs/DEVELOPER_GUIDE.md).

---

## License

Copyright © 2024–2026 MedICS Team. All rights reserved.

MedICS is proprietary software. See [LICENSE.md](LICENSE.md) for the full terms.

MedICS is built on [PySide6/Qt](https://doc.qt.io/qtforpython/), [NumPy](https://numpy.org/), [SciPy](https://scipy.org/), [pydicom](https://pydicom.github.io/), [h5py](https://www.h5py.org/), [scikit-image](https://scikit-image.org/), [Matplotlib](https://matplotlib.org/), [napari](https://napari.org/), [pyqtgraph](https://www.pyqtgraph.org/), [qtconsole](https://qtconsole.readthedocs.io/), and [numba](https://numba.pydata.org/).
