View on GitHub

AVIS-DICOM

documentation on the project for processing DICOM images

Boon Logic

API Documentation

This REST API serves as an interface into the BoonLogic AVIS-DICOM server for processing test mammography images.

GET /status

Is a generic API call to serve as a basic test to determine if the server is on and connected in a functioning way.

Request
None

Response
String timestamp of the execution

Example 

curl -X GET http://localhost:8080/avis-dicom/v1/status

GET /version

A status call to get the unique version numbers of the individual software components running on the backend.

Request
None

Response
JSON block of the software components and their corresponding version numbers

{
  "avis-dicom-api": "8f7e7b89",
  "avis-dicom-common": "80928067",
  "builder": "5b6ee068",
  "expert-common": "fdcf08e5",
  "nano-py-bindings": "ac00aa9e",
  "nano-secure": "7930648e",
  "release": "v2.4.2"
}

Example 

curl -X GET http://localhost:8080/avis-dicom/v1/version

POST /testBench

Connects an identifier for a given test bench to the server. For future calls, this identifier servers as a simple authorization for future calls to that test bench

HTTP headers
–x-token=${idToken}

Request
identifier: (string) label for the test bench

{
  "serial": "serial",
  "status": "status"
}

Response
JSON block containing the identifier and the pipeline status for that test bench

Example 

curl -X POST \
    --url http://localhost:8080/avis-dicom/v1/testBench/{identifier} \
    --Header "x-token: test"

Error conditions
400 - duplicate test bench identifiers

GET /testBench

Gets the status information associated with the given test bench identifier.

HTTP headers
–x-token=${idToken}

Request
identifier: (string) label for the test bench

Response
JSON block containing the identifier and the pipeline status for that test bench

{
  "serial": "serial",
  "status": "Done: waiting for image"
}

Example 

curl -X GET \
    --url http://localhost:8080/avis-dicom/v1/testBench/{identifier} \
    --Header "x-token: test"

Error conditions
400 - given identifier is not a connected test bench

DELETE /testBench

Removes the test bench identifier from the list of valid test benches to communicate with the server.

HTTP headers
–x-token=${idToken}

Request
identifier: (string) label for the test bench

Response
JSON block containing the return code and a brief message about the success of the call

{
  "code": 200,
  "message": "test bench was successfully disconnected"
}

Example 

curl -X DELETE \
    --url http://localhost:8080/avis-dicom/v1/testBench/{identifier} \
    --Header "x-token: test"

Error conditions
400 - given identifier is not a connected test bench

GET /testBenches

Gets the list of connected test bench identifiers and each one’s status information.

HTTP headers
–x-token=${idToken}

Request
None

Response
JSON block containing a list of identifiers and the pipeline status for each test bench

[
  {
    "serial": "serial-1",
    "status": "Done: waiting for image"
  },
  {
    "serial": "serial-2",
    "status": "Done: results available for image FilterMoMo_LF_1292019_121230_PM"
  }
]

Example 

curl -X GET \
    --url http://localhost:8080/avis-dicom/v1/testBenches \
    --Header "x-token: test"

POST /configuration

Sets various parameters for processing the images.

HTTP headers
–x-token=${idToken}

Request
kernelSize: (integer) number of pixels wide for each sub-image processed (default: 75)

filterType: (string) filter for overall image: gaussian, median, none (default: none)

filterParam: (decimal) sigma or radius value corresponding with the filter (default: 1)

candidateSize: (integer) number of pixels wide to display for each sub-image processed (default: kernelSize)

major: (decimal) Rose model threshold for major candidates (default: 0.9)

minor: (decimal) Rose model threshold for minor candidates (default: 0.5)

edgeCrop: (integer) number of pixels to trim along the edge (default: 3)

sfEdge: (integer) pixel width to trim for SF images (trims off right side of image) (default: 1290)

a0SF: (decimal) candidate area minimum asymptote for SF images (default: 11)

a0LF: (decimal) candidate area minimum asymptote for LF images (default: 9)

c0: (decimal) candidate contrast minimum asymptote (default: 0.015)

w: (decimal) determines steepness of Rose model contours with higher values being more gradual slope (default: 2.1)

k0: (decimal) determines steepness of Rose model curve with higher values being more gradual slope (default: 2)

areaMax: (integer) candidate area maximum to use Rose model. Areas above are automatically major (default: none)

contrastMax: (decimal) candidate contrast maximum to use Rose model. Contrasts above are automatically major (default: none)

Response
JSON block containing a complete list of the parameters including both the set values and the ones autotuned in the pipeline.

{
  "image": "FilterRhAg_SF_TestFilters_1909863.DPm_9172019_54221_PM.MGDC",
  "subcell": {
    "width": 101,
    "shift": 33
  },
  "max": 159,
  "preprocess": {
    "filter": "gaussian",
    "parameter": 1,
    "edge": 3,
    "SFedge": 1290
  },
  "thresholds": {
    "variation": 0.07,
    "major": 0.95,
    "minor": 0.5,
    "anomaly": 254,
    "distance": 256,
    "areaMax": 60,
    "contrastMax": 0.3
  },
  "roseConstants": {
    "a0SF": 11,
    "a0LF": 9,
    "c0": 0.015,
    "w": 2.1,
    "k0": 2
  }
}

Example 

curl -X POST \
     --url http://localhost:8080/avis-dicom/v1/configuration/{identifier} \
           ?kernelSize=101 \
           &edgeCrop=10 \
           &c0=0.02 \
           &filterType=gaussian \
           &filterParam=1 \
     --Header "x-token: test"

Error conditions
400 - given identifier is not a connected test bench
  - invalid parameter name specified
  - filter is not one of: “gaussian”, “median”, or “none”

GET /configuration

Sets various parameters for processing the images.

HTTP headers
–x-token=${idToken}

Request
identifier: (string) label for the test bench

Response
JSON block containing a complete list of the parameters including both the set values and the ones autotuned in the pipeline.

{
  "image": "FilterRhAg_SF_TestFilters_1909863.DPm_9172019_54221_PM.MGDC",
  "subcell": {
    "width": 101,
    "shift": 33
  },
  "max": 159,
  "preprocess": {
    "filter": "gaussian",
    "parameter": 1,
    "edge": 3,
    "SFedge": 1290
  },
  "thresholds": {
    "variation": 0.07,
    "major": 0.95,
    "minor": 0.5,
    "anomaly": 254,
    "distance": 256,
    "areaMax": 60,
    "contrastMax": 0.3
  },
  "roseConstants": {
    "a0SF": 11,
    "a0LF": 9,
    "c0": 0.015,
    "w": 2.1,
    "k0": 2
  }
}

Example 

curl -X GET \
     --url http://localhost:8080/avis-dicom/v1/configuration/{identifier}
     --Header "x-token: test"

Error conditions
400 - given identifier is not a connected test bench

POST /rawImage

Loads an image and runs the AVIS-DICOM pipeline on the given image.

HTTP headers
–x-token=${idToken}

Request
identifier: (string) label for the test bench filetype: (string) file type being uploaded. Can be either dcm or png upfile: (data) image to process

Response
JSON block containing the return code and a brief message about the success of the call

{
  "code": 200,
  "message": "test bench was successfully disconnected"
}

Example 

curl -X POST \
     --url http://localhost:8080/avis-dicom/v1/rawImage/{identifier} \
           ?filetype=dcm \
     --Header "x-token: test" \
     --Header  "accept: application/json" \
     --Header  "Content-Type: multipart/form-data" \
     -F "upfile=@/path/to/file.DICOM"

Error conditions
400 - given identifier is not a connected test bench
  - subcell parameter is too big for image
  - edge parameter is too big for image

GET /results

Prints out the latest image results including the number of major and minor defects and the coordinates for the major defects

HTTP headers
–x-token=${idToken}

Request
identifier: (string) label for the test bench

Response
JSON block containing the list of coordinates for the major defects as well as the number of minor and major defects found

{
  "image": "FilterRhAg_SF_TestFilters_1909863.DPm_9172019_54221_PM.MGDC",
  "major": 1,
  "minor": 3,
  "coordinates": {
    "major": [
      [
        0,
        0
      ]
    ],
    "minor": [
      [
        10,
        10
      ],
      [
        200,
        1
      ],
      [
        3,
        725
      ]
    ]
  },
  "contrasts": {
    "major": [
      0.025
    ],
    "minor": [
      0.019,
      0.013,
      0.01
    ]
  },
  "areas": {
    "major": [
      45
    ],
    "minor": [
      3,
      2,
      7
    ]
  }
}

Example 

curl -X GET \
     --url http://localhost:8080/avis-dicom/v1/results/{identifier} \
     --Header "x-token: test"

Error conditions
400 - given identifier is not a connected test bench
  - no image processed

GET /summary

Returns a summary pdf that displays the original image with highlighted areas where the minor and major defects were found. In addition, there is a column of zoomed in defect sub-images with each ones coordinates and calculated contrast value associated with it. All candidates are contrast stretched the same and the window width and window level used is listed above the defect sub-images.

HTTP headers
–x-token=${idToken}

Request
identifier: (string) label for the test bench

Response
file: named after the original image with a “-summary” appended

Example 

curl -X GET \
     --url http://localhost:8080/avis-dicom/v1/summary/{identifier} \
     --Header "x-token: test"

Error conditions
400 - given identifier is not a connected test bench
  - no image processed