AIAA Server APIs
Once you have AIAA server running, you can also check detailed schema
for every API at: http://127.0.0.1:$LOCAL_PORT/docs.
The $LOCAL_PORT is the port you use when launching the container in Installation.
Admin APIs are host controlled. When you start the AIAA server you can use --admin_hosts option to
specify from which client hosts you can invoke the following APIs. The default is * which means
no restrictions, that is every client can invoke Admin APIs.
Following are the important ones:
GET Model
You can get the current configuration for a given model by using this command.
curl -X GET "http://127.0.0.1:$LOCAL_PORT/admin/model/clara_ct_seg_spleen_amp" \
-H "accept: application/json"
PATCH Model
If you want to update the config only (without updating the model), you can do so by refreshing the configs and reloading an existing model with new configs.
curl -X PATCH "http://127.0.0.1:$LOCAL_PORT/admin/model/clara_ct_seg_spleen_amp" \
-H "Content-Type: application/json" \
-d @config_aiaa.json
PUT Model
This API will help to load a model into AIAA server.
curl -X PUT "http://127.0.0.1:$LOCAL_PORT/admin/model/clara_ct_seg_spleen_amp" \
-F "config=@config_aiaa.json;type=application/json" \
-F "data=@model.trt.pb"
Refer to Loading Models for detailed usage of loading a model.
DELETE Model
You can remove the model from AIAA server using this API.
curl -X DELETE "http://127.0.0.1:$LOCAL_PORT/admin/model/clara_ct_seg_spleen_amp"
If you have multiple AIAA server running and they share common workspace for saving all the models
and configurations, you should enable --auto_reload option while starting the AIAA Server.
This will help to keep all the AIAA Server in sync when a model is loaded/updated/removed.
APIs that are designed for all regular clients.
models
List models loaded in AIAA Server
# Query All Models
curl -X GET "http://127.0.0.1:$LOCAL_PORT/v1/models"
# Query Matching Models for a given Label and Type
curl -X GET "http://127.0.0.1:$LOCAL_PORT/v1/models?label=spleen&type=segmentation"
# Query Specific Model
curl -X GET "http://127.0.0.1:$LOCAL_PORT/v1/models?model=clara_ct_seg_spleen_amp"
segmentation
Run Segmentation model in AIAA Server for an input image.
curl -X POST "http://127.0.0.1:$LOCAL_PORT/v1/segmentation?model=clara_ct_seg_spleen_amp&output=image" \
-H "accept: multipart/form-data" \
-H "Content-Type: multipart/form-data" \
-F "params={}" \
-F "image=@spleen.nii.gz;type=application/x-gzip" \
-o output_image.nii.gz
dextr3d
Run DExtr3D in AIAA Server for an input image and extreme points.
curl -X POST "http://127.0.0.1:$LOCAL_PORT/v1/dextr3d?model=clara_ct_annotation_spleen_amp&output=image" \
-H "accept: multipart/form-data" \
-H "Content-Type: multipart/form-data" \
-F "params={\"points\":\"[[93,106,64],[40,108,64],[29,66,64],[47,20,64],[93,32,64],[99,68,64]]\"}" \
-F "image=@cropped_spleen.nii.gz;type=application/x-gzip" \
-o output_image.nii.gz
deepgrow
Run DeepGrow in AIAA server given foreground/background points.
curl -X POST "http://127.0.0.1:$LOCAL_PORT/v1/deepgrow?model=clara_deepgrow&output=image" \
-H "accept: multipart/form-data" \
-H "Content-Type: multipart/form-data" \
-F "params={\"foreground\":\"[[155, 189, 78], [184, 192, 78], [114,225,78]]\", \"background\":\"[]\"}" \
-F "image=@spleen.nii.gz;type=application/x-gzip" \
-o output_image.nii.gz
inference
Run inference on any generic model in AIAA server.
Please refer to Model Config for details on type of models supported in AIAA.
curl -X POST "http://127.0.0.1:$LOCAL_PORT/v1/inference?model=my_model&output=image" \
-H "accept: multipart/form-data" \
-H "Content-Type: multipart/form-data" \
-F "params={\"mydata\":[1,2,3]}" \
-F "image=@spleen.nii.gz;type=application/x-gzip" \
-o output_image.nii.gz
You can use /inference API to run model pipelines, classification models etc.
mask2polygon
Given a 3D mask in NIFTI file, generate polygons (0 or more) on each 2D slices.
curl -X POST "http://127.0.0.1:$LOCAL_PORT/v1/mask2polygon" \
-H "accept: application/json" \
-H "Content-Type: multipart/form-data" \
-F "params={ "more_points": 10 }" \
-F "image=@mask2polygon.input.nii.gz;type=application/gzip"
fixpolygon
Adjust the polygons to a better fit 2D/3D polygons.
# 2D Image/Input => Output: Result Json
curl -X POST "http://127.0.0.1:$LOCAL_PORT/v1/fixpolygon?output=results" \
-H "accept: multipart/form-data" \
-H "Content-Type: multipart/form-data" \
-F "params=`cat fixpolygon.input.json`" \
-F "image=@fixpolygon.input.png;type=image/png" \
-o new_polygons.json
# 2D Image/Input => Output: Image
curl -X POST "http://127.0.0.1:$LOCAL_PORT/v1/fixpolygon?output=image" \
-H "accept: multipart/form-data" \
-H "Content-Type: multipart/form-data" \
-F "params=`cat fixpolygon.input.json`" \
-F "image=@fixpolygon.input.png;type=image/png" \
-o new_mask.png
# 3D Image/Input => Output: Image
curl -X POST "http://127.0.0.1:$LOCAL_PORT/v1/fixpolygon?output=image" \
-H "accept: multipart/form-data" \
-H "Content-Type: multipart/form-data" \
-F "params=`cat fixpolygon.3d.input.json`" \
-F "image=@label.nii.gz;type=application/x-gzip" \
-o new_label.nii.gz
The following is a schema for the FixPolygon input json file.
Field |
Description |
|---|---|
dimension |
Dimension to represent 2D or 3D |
poly |
Represents new polygon points (not required if vertex_offset is used) |
prev_poly |
Represents current polygon points |
slice_index |
Represents current slice in case of 3D image |
polygon_index |
Represents modified polygon index among poly |
vertex_index |
Represents modified vertex index |
vertex_offset |
Represents new vertex after adding offset (x,y) for 2D/3D |
propagate_neighbor |
Propagation size for neighborhood |
propagate_neighbor_3d |
Propagation size for neighborhood in case of 3D |
Clients can choose to create a session for an image to reduce the time in consecutive requests.
This is recommended if users are interacting using DExtr3D or DeepGrow API with 3D volumes.
Users pay this one time cost to upload the image to the server, and the following requests
will be faster because the image does not need to be uploaded again.
You can specify expiry in seconds when creating a session to decide the time that this session would live.
PUT Session
Create a new AIAA session and upload an image as part of the session.
curl -X PUT "http://127.0.0.1:$LOCAL_PORT/session/?expiry=30" \
-H "accept: application/json" \
-H "Content-Type: multipart/form-data" \
-F "image=@spleen.nii.gz;type=application/x-gzip"
You can also provided a DICOM server address so that AIAA will fetch images from there.
Let’s assume you have a DICOM server DCM4CHEE running at ip 0.0.0.0, and the AE DCM4CHEE listens on port 11112.
Then you put the ip, port, ae_title and id of patient, study and series in a json file (data.json) as follows:
{
"dicom": {
"server_address": "0.0.0.0",
"server_port": 11112,
"ae_title": "DCM4CHEE",
"query_level": "PATIENT",
"patient_id": "ProstateX-0004",
"study_uid": "1.3.6.1.4.1.14519.5.2.1.7311.5101.170561193612723093192571245493",
"series_uid": "1.3.6.1.4.1.14519.5.2.1.7311.5101.206828891270520544417996275680"
}
}
Now you can ask AIAA to fetch the data from DICOM server and create a session using the following command:
curl -X PUT "http://127.0.0.1:$LOCAL_PORT/session/?expiry=30" \
-H "accept: application/json" \
-d "@data.json"
AIAA also supports getting data using HTTP requests.
Assume you have a image server running and you can download the data using a url.
You can prepare a data.json file that contains this information.
For example:
{
"http": {
"url": "http://0.0.0.0/data/projects/NV_CLARA/subjects/XNAT_S00001/experiments/XNAT_E00002/scans/49621430/resources/DICOM/files",
"params": {
"format": "zip"
},
"method": "GET"
}
}
Then you ask AIAA to fetch the data based on this config, that is using HTTP Get method on this url. AIAA will create the session after the data is fetched.
curl -X PUT "http://127.0.0.1:$LOCAL_PORT/session/?expiry=30" \
-H "accept: application/json" \
-d "@data.json"
AIAA utilizes pynetdicom to do c_get to fetch the data from DICOM server. You can refer to their documentation for more information.
AIAA uses requests library to handle the HTTP fetch. Please refer to request documentation for optional arguments.
GET Session
Retrieve saved session/image document available from the server.
curl -X GET "http://127.0.0.1:$LOCAL_PORT/session/[session_id here]?image=false" \
-H "accept: application/octet-stream"
DELETE Session
Close an existing session.
curl -X DELETE "http://127.0.0.1:$LOCAL_PORT/session/[session_id here]"