README

Overview

The ImageTransformSvc creates missing levels in a whole slide image, and standardizes the WSI format to DICOM.

The service is built using FastAPI and the conversion is based on the wsidicom and wsidicomizer libraries. For long-running conversion tasks, Celery is used to run the conversion in the background and the progress can be tracked via Flower on port 5555. The service is designed to be deployed as a Docker container.

Links

Swagger API

Repo

Project Work Items

Feature List

Multiple WSI/Image File Formats
Add missing levels or metadata to the converted DICOM
Cross Platform (Linux/Win)
Multithreaded Request Processing
Detailed Logging (Request Level Logging)
Configuration
Documentation Site - independent documentation site mounted as static application

Roadmap

WSI/Image File Formats

Currently Supported

- Aperio (.svs)
- Hamamatsu (.ndpi)
- Philips (.tiff)
- Zeiss (.czi)
- Mirax (.mrxs)
- Leica (.scn)
- Sakura (.svslide)
- Trestle (.tif)
- Ventana (.bif, .tif)
- Hamamatsu (.vms, .vmu)
- DICOM (single or multi level)
- PNG, JPEG, TIFF, BMP, etc.

Currently In-development (12/14/23)

{}

Setup

See SETUP.md in repo for setup instructions

https://gestaltdiagnostics.visualstudio.com/Gestalt%20AI/_git/ImageTransformSvc?path=/docs/docs/setup/SETUP.md

Enhancements

See DEVELOPMENT.md for list of fixes/enhancements

https://gestaltdiagnostics.visualstudio.com/Gestalt%20AI/_git/ImageTransformSvc?path=/docs/docs/DEVELOPMENT.md

API Documentation

Primary API root is labeled /api
- All methods available under this root.

API Overview

All methods are of type PUT and consist of an input source and a target for the converted images:

Source can be one of two types:
- path: A relative or absolute path to a file or directory on the server.
- wsi: A file to be uploaded to the server. Files which consist of multiple images (e.g. .mrxs) need to be uploaded as a ZIP.
Target can be one of three types:
- dcm: Converts the input WSI to a DICOM file for immediate download.
- dcmweb: Converts the input WSI to a DICOM file and uploads it to a DICOMweb server. The conversion returns a Flower tracking id which can be used to track the progress of the conversion.
- dcmfolder: Converts the input WSI to a DICOM file and saves it to a folder on the server. The conversion returns a Flower tracking id which can be used to track the progress of the conversion.

/api/transform/{path|wsi}2{dcm|dcmweb|dcmfolder}

Example

Convert a file path to DICOM and store the results in a folder.

curl -X 'PUT' \
  'http://127.0.0.1:8020/transform/path2dcmfolder?dcm_input=SVS%2F00D91A64-A6A6-4A06-BAAC-C445D83824B4%2F00D91A64-A6A6-4A06-BAAC-C445D83824B4.svs&target_folder=SVS_00D91A64-A6A6-4A06-BAAC-C445D83824B4' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \

If Celery is active, the response will include a tracking number:

{
  "task_id": "4f45731b-8396-468c-a534-03a029893b75",
  "status": "http://localhost:5555/task/4f45731b-8396-468c-a534-03a029893b75",
  "warnings": ""
}

Which can be used to track the progress of the conversion.

curl -X 'GET' \
  'http://127.0.0.1:8020/transform/task/4f45731b-8396-468c-a534-03a029893b75' \
  -H 'accept: application/json'

Response:

{
  "task_id": "4f45731b-8396-468c-a534-03a029893b75",
  "task_status": "SUCCESS",
  "task_error": null
}

API Methods

Method	Description
`/api/transform/path2dcm`	Convert a file path to DICOM and return the result as a ZIP archive.
`/api/transform/wsi2dcm`	Convert an uploaded file or image archive(zip) to DICOM and return the result as a ZIP archive.
`/api/transform/path2dcmweb`	Convert a file path to DICOM and upload the results to a DICOMWeb endpoint. Returns a Flower tracking number.
`/api/transform/wsi2dcmweb`	Convert an uploaded file or image archive(zip) to DICOM and upload the results to a DICOMWeb endpoint. Returns a Flower tracking number.
`/api/transform/path2dcmfolder`	Convert a file path to DICOM and store the result in a folder. Returns a Flower tracking number.
`/api/transform/wsi2dcmfolder`	Convert an uploaded file or image archive(zip) to DICOM and store the result in a folder. Returns a Flower tracking number.

API Parameters

Parameter	Type	Default	Description	Methods
input_file	str	Reqired	The path to the server file for DICOM conversion	path2*
file	File	Reqired	The file or image archive(zip) to convert to DICOM	wsi2*
url	str	None	URL to DICOMWeb service for uploading the converted DCM files	*2dcmweb
headers	json/str	None	Please, provide the headers as a string representation of the dictionary	*2dcmweb
target_folder	str	Reqired	Folder on the server to save the converted DICOM files	*2dcmfolder
dataset	JSON File	None	F.2.1.1.2 DICOM JSON Model as defined in https://dicom.nema.org/dicom/2013/output/chtml/part18/sect_F.2.html	*
tile_size	int	512	Tile size (same for width and height).	*
include_levels	array[integer]	[ 0, 1, 2, 3, 4, 5, 6 ]	Pyramid levels to include, if not all. E.g. 0 1 for base and first pyramid layer.	*
include_overview	bool	True	If to include the overview image	*
include_label	bool	True	If to include the label image	*
include_confidential	bool	True	If to include confidential metadata	*
chunk_size	int	16	Number of tiles to give each worker at a time.	*
workers	int	NumCores	Number of worker threads to use, default to number of cores	*
encoding_format	str	jpeg	Encoding format to use if re-encoding. 'jpeg' or 'jpeg2000'.	*
encoding_quality	int	90	Quality to use if re-encoding. It is recommended to not use > 95 for jpeg. Use < 1 or > 1000 for lossless jpeg2000.	*
jpeg_subsampling	int	420	Subsampling option if using jpeg for re-encoding. Use '444' for no subsampling, '422' for 2x1 subsampling, and '420' for 2x2 subsampling.	*
offset_table	str	eot	Offset table to use, 'bot' basic offset table, 'eot' extended offset table, 'None' - no offset table.	*

ping

Returns message indicating ImageTransformSvc is functioning

Parameters:

Format: /ping
Example/Test: http://192.168.150.11:50099/transform/ping

Docker

Use one of the docker-compose*.yml files in project root directory to build and run container

```bash
docker docker-compose.poc-linux-1.yml up --build -b

Gunicorn

Gunicorn config in project roote: gunicorn.conf.py
Launch line: gunicorn app:app --config ../gunicorn.conf.py

Tests

The tests are located in tests directory. The tests can be run via the comand line argument:

pytest