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
  • Table of contents
  • Introduction
  • Features
  • The image model: MedImage
  • Get started
    • Requirements
    • Install
    • Launch
    • Basic workflow
  • Toolboxes
  • Extensions
    • Install an extension
    • Create an extension
    • Build and publish
  • 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 — 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.

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

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 → Full API reference: 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

pip install medics

Verify

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

Launch

medics
# or
python -m medics

Useful CLI commands:

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

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

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:

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:

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

{
  "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)

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

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 and medics/extension_template/docs/DEVELOPER_GUIDE.md.

---

License

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

MedICS is proprietary software. See LICENSE.md for the full terms.

MedICS is built on PySide6/Qt, NumPy, SciPy, pydicom, h5py, scikit-image, Matplotlib, pyqtgraph, qtconsole, and numba.