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

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:

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.

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, napari, pyqtgraph, qtconsole, and numba.