spine-harmony-agent

MRI/DICOM Imaging Workflow

MRI/DICOM export and assisted review is a core Spine Harmony workflow. It helps users convert their own imaging files into high-resolution review images, organize those images with the rest of their spine-health materials, and prepare better questions for qualified clinicians.

What the workflow can do

Depending on the local tools available, the workflow may:

• read user-owned DICOM/MRI series;
• export high-resolution PNG/JPEG review images;
• organize images by study, series, orientation, or selected view;
• create contact sheets for rapid review;
• place selected images alongside radiology reports, symptom notes, and Q&A logs;
• use the user’s chosen LLM or vision model to produce explanatory, non-clinical observations for clinician-question preparation;
• turn those observations into better questions for radiologists, spine surgeons, physiotherapists, or other qualified clinicians.

Concrete conversion instructions

Spine Harmony includes a reference DICOM export utility at:

tools/dicom-export/dicom_export.py

1. Install dependencies

From the repository root:

python -m pip install -r tools/dicom-export/requirements.txt

Equivalent manual install:

python -m pip install pydicom pillow numpy

2. Put DICOM files in a private local folder

Use a folder outside version control, for example:

/private/path/to/my-dicom-study/

Do not place real DICOM files inside this public repository. DICOM metadata may contain personal medical information.

3. Export high-resolution PNG review images

python tools/dicom-export/dicom_export.py /private/path/to/my-dicom-study /private/path/to/spine-harmony-exports

The tool recursively scans the input folder, reads DICOM files, applies DICOM rescale/windowing where available, and writes PNG files grouped by series. It does not downsample source pixel data.

Example output:

/private/path/to/spine-harmony-exports/
├── series-001_T2_SAG/
│   ├── series-001_instance-0001_T2_SAG.png
│   ├── series-001_instance-0002_T2_SAG.png
│   └── ...
├── series-002_T1_AXIAL/
│   └── ...
└── export_manifest.csv

4. Create a contact sheet

python tools/dicom-export/dicom_export.py /private/path/to/my-dicom-study /private/path/to/spine-harmony-exports --contact-sheet

This also creates:

contact_sheet.jpg

Use contact sheets for fast orientation and consultation preparation. Do not treat contact sheets as diagnostic images.

5. Use exported images in Q&A

A safe prompt pattern is:

These are converted review images from my own MRI study. Please help me organize what questions to ask my clinician. Do not diagnose, do not provide treatment advice, and clearly separate visual observations from clinical interpretation.

A good Spine Harmony response should use language such as:

The model appears to notice...
This may be worth asking your clinician about...
This should be checked against the formal radiology report...

It should avoid language such as:

The MRI proves...
You have...
You need...

6. Troubleshooting

If no images are exported:

• confirm the input folder actually contains DICOM files;
• try pointing the tool at the top-level folder from the imaging CD/portal export;
• confirm dependencies installed successfully;
• check whether the files are compressed DICOMs requiring additional pixel-data handlers;
• use a clinical DICOM viewer to confirm the source files open correctly.

If images look inverted or too dark/bright:

• confirm whether the source series uses MONOCHROME1 or unusual windowing;
• compare with the formal viewer supplied by the imaging provider;
• do not infer clinical meaning from display differences alone.

What the workflow must not claim

The workflow must not claim to provide:

• radiology interpretation;
• diagnosis;
• validated measurements;
• segmentation;
• surgical candidacy decisions;
• treatment recommendations;
• emergency triage;
• replacement for a radiologist, surgeon, physician, or other qualified clinician.

LLM / vision-model responsibility and wording limits

The image-review text is generated by the user’s chosen LLM or vision model/runtime. Spine Harmony does not validate, certify, control, or guarantee that model. Outputs may be wrong, incomplete, overconfident, misleading, or inconsistent with the actual imaging and clinical record.

Use model-generated image observations only as a prompt for further questions and clinician discussion. Do not use them instead of radiologist reporting, clinician interpretation, diagnosis, treatment planning, validated measurement, or emergency care. Do not describe the workflow as safe, validated, clinically reliable, regulator-approved, or suitable for unsupervised medical use.

Privacy and de-identification

DICOM files often contain personal information in metadata, including patient name, internal identifiers, study date, institution, study/reference numbers, and device/site details. Some images may contain burned-in annotations.

Treat all of the following as sensitive medical data:

• raw DICOM files;
• converted images;
• screenshots;
• contact sheets;
• metadata dumps;
• LLM-generated imaging notes;
• reports containing image-derived observations.

Do not commit real imaging files or derived outputs to a public repository. Use synthetic or properly de-identified public test data only.

Recommended output language

Use cautious phrasing such as:

“The model appears to notice…”

“This could be a question to ask your clinician…”

“This should be checked against the formal radiology report and a qualified clinician’s interpretation.”

Avoid phrasing such as:

“The MRI shows…”

“You have…”

“This means you need…”

This site is open source. Improve this page.