Skip to main content Skip to secondary navigation

Developer Documentation

Main content start

ePAD REST API (An Introduction)

  • Complete Resource List
  • Connecting to the ePAD REST API
  • Create Subjects via REST
  • Upload Files via REST
  • Download Files via REST
  • Query the Search Engine via REST
  • ePAD Session Management


The AIM API is an open source application interface in Javascript for reading and writing JSON AIM files. The AIM API makes working with AIM easy in Javascript.

Spline is one of the drawing options of ePad. However, AIM structure does not contain Spline as a geometric shape. For that reason, we implemented an additional geometric shape class called as Spline in the AIM API. Instances of the Spline class are stored as TwoDimensionPolyLine in the AIM XML files. We append a keyword to uniqueIdentifier of the TwoDimensionPolyLine instance to identify if it is a Spline or not. While reading and writing AIM XML files this operation is done automatically by the AIM API.

ePAD Developer Tools

Use David Clunie’s dciodvfy validator from his dicom3tools kit. It can be downloaded from

To validate a DICOM file:
dciodvfy [DICOM FILE]
To see all headers:
dciodvfy -dump [DICOM FILE]
The following page gives an explanation of common header errors:

Building ePAD Software Components

This page describes the process of downloading ePAD from GitHub.

ePADlite is composed of the following software components that are being developed by our group. All are developed with Javascript. You can clone each using the commands listed and contribute

  • ePAD_js (React UI client) : git clone
  • ePAD_lite (nodejs REST API developed with fastify framework): git clone
  • DICOMweb Server (nodejs DICOMweb server developed with fastify framework): git clone
  • AIM API JS (javascript library for creating/editing AIMs): git clone
  • epad-dist (distribution package): git clone
  • AimConvert (a nodejs commandline tool to convert old XML AIM and AIM Template files to new JSON format):  git clone
  • Template Builder (a tool to build new AIM Templates developed with React framework): git clone

Installing an ePAD Plugin

  • Push your plugin to docker hub
  • Create the plugin entry in ePAD and fill in the plugin parameters
  • Process varies according to the parameters of your plugin. You can see the sample process for pyradiomics plugin here

Writing an ePAD Plugin

ePAD supports dockerized plugins. ePAD plugins are interchangable with QIFP plugins. 
Create a dockerized program that takes the following inputs 

  • A folder containing DICOM images
  • A folder containing DSOs (for extraction of 3D features)
  • A folder containing AIM files (for extraction of 2D features)
  • An optional configuration file
  • A folder to which output file(s) should be written

For example, the linux command line for the program could be:
# featureExtractor  /tmp/dsos /tmp/dicoms  /tmp/output  /tmp/config.ini

Where the first three parameters are folder paths and last one is a file path (the path names could change so do not hard-code any path or filename, use the parameters as passed)

The output should consist of a csv file in which the first column is a list of feature names and the header row is a list of Patient IDs (from the dicom images). So the column under the Patient ID contains decimal values for the corresponding extracted feature. Besides the feature values, the first few rows of the file should contain the following:

  • PatientName
  • SeriesInstanceUID
  • StudyInstanceUID
  • Segmentation UID (or DSO Image UID)
  • DSO Series UID
  • AIM ID  (if applicable)

The docker image generated should be then pushed to a DockerHub account.