Images - dsimaging/dsio-filters-api Wiki

This page is concerned with managing image resources for processing.

Create Image Resource

POST/images

This method creates a new image resource by uploading a 16-bit grayscale PNG image file and corresponding information about the image. The request must be formatted as a Multipart Form Data request with a body that includes both the image file and the JSON data describing the image. When filter operations are complete, the resource should be deleted with the Delete Image Resource API call. If the Delete Image Resource call is not used, the resource will be deleted automatically after the expires timestamp.

Authorization

BasicAuth

Path Parameter

No parameters

Request

Request body schema: multipart/form-data

Body Parts

The following parts must be included in the multipart/form-data request.

Field Name Content Type Description
imageInfo application/json Contains an ImageInfo object that describes information about the image used to create an ImageResource. This information should be obtained directly from the corresponding ImageInfo object of the image acquired using the DSIO Modality API. Note that this object is a subset of the DSIO Modality API, thus allowing API consumers to use the same object for both. This json data must be formatted as a single line of text.
imageMedia image/png The media file to upload. This file must be a 16-bit PNG image in binary format.

Example

The following is an example of the body content for a multipart/form-data request:

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="imageInfo"
Content-Type: application/json

{"acquisitionInfo":{"binning":"Binned2X2"},"lutInfo":{"gamma":2.3,"slope":65535,"offset":0,"totalGrays":4096,"minimumGray":3085,"maximumGray":0}}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="imageMedia"; filename="/C:/UnfilteredImage_1c577c7a-ab22-4cee-b03b-41ef69958dff.png"
Content-Type: image/png

(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW

Responses

201 Image resource created

400 Bad input parameter

415 Unsupported media type

Response schema: application/json

Body

Name Description
ImageResource Represents an ImageResource uploaded for processing.

Example

{
"id": "160c98f9-d188-4118-94c4-697161fd5caf",
"mediaType": "image/png",
"url": "https://example.com/images/160c98f9-d188-4118-94c4-697161fd5caf/file.png",
"createdOn": "2021-05-03T14:56:00.000Z",
"expires": "2021-05-03T22:56:00.000Z",
"imageInfo": {
    "acquisitionInfo": {
      "binning": "Unbinned"
    },
    "lutInfo": {
      "gamma": 2.3,
      "slope": 65535,
      "offset": 0,
      "totalGrays": 4096,
      "minimumGray": 3612,
      "maximumGray": 418
    }
  },
 "modalitySession": null
}

Create Modality Resource

POST/images/modality

This method creates a new image resource by referencing an image captured in a current modality session. This resource will only be available for as long as the modality session is active. When filter operations are complete, the resource should be deleted with the Delete Image Resource API call. If the Delete Image Resource call is not used, the resource will be deleted automatically after the expires timestamp.

Authorization

BasicAuth

Path Parameter

No parameters

Request

Request body schema: application/json

Body

Name Type Description
sessionId string Id of the modality session
imageId string Id of the image acquired by the modality

Example

{
  "sessionId": "451f7e06-5827-4c99-b6fb-b9c330ca922c",
  "imageId": "39db323b-198d-4219-b79e-ca918cde5be5"
}

Responses

201 Image resource created

400 Bad input parameter

404 Modality session or image not found

Response schema: application/json

Body

Name Description
ImageResource Represents an ImageResource uploaded for processing.

Example

{
"id": "160c98f9-d188-4118-94c4-697161fd5caf",
"mediaType": "image/png",
"url": "https://example.com/images/160c98f9-d188-4118-94c4-697161fd5caf/file.png",
"createdOn": "2021-05-03T14:56:00.000Z",
"expires": "2021-05-03T22:56:00.000Z",
"imageInfo": {
    "acquisitionInfo": {
      "binning": "Unbinned"
    },
    "lutInfo": {
      "gamma": 2.3,
      "slope": 65535,
      "offset": 0,
      "totalGrays": 4096,
      "minimumGray": 3612,
      "maximumGray": 418
    }
  },
 "modalitySession": {
    "sessionId": "451f7e06-5827-4c99-b6fb-b9c330ca922c",
    "imageId": "39db323b-198d-4219-b79e-ca918cde5be5"
  }
}

Get Image Resource

GET/images/{id}

This method retrieves an image resource.

Authorization

BasicAuth

Path Parameter

Parameter Type Required? Description
id string Yes Id of the image resource to retrieve

Responses

200 Success

404 Image resource not found

Response schema: application/json

Body

Name Description
ImageResource Represents an ImageResource uploaded for processing.

Example

{
"id": "160c98f9-d188-4118-94c4-697161fd5caf",
"mediaType": "image/png",
"url": "https://example.com/images/160c98f9-d188-4118-94c4-697161fd5caf/file.png",
"createdOn": "2021-05-03T14:56:00.000Z",
"imageInfo": {
    "acquisitionInfo": {
      "binning": "Unbinned"
    },
    "lutInfo": {
      "gamma": 2.3,
      "slope": 65535,
      "offset": 0,
      "totalGrays": 4096,
      "minimumGray": 3612,
      "maximumGray": 418
    }
  },
 "modalitySession": {
    "sessionId": "451f7e06-5827-4c99-b6fb-b9c330ca922c",
    "imageId": "39db323b-198d-4219-b79e-ca918cde5be5"
  }
}

Delete Image Resource

DELETE/images/{id}

This method deletes an image resource from the filters service. This image will no longer be available for processing.

Authorization

BasicAuth

Path Parameter

Parameter Type Required? Description
id string Yes Id of the image resource to delete. Please note that if the resource was created from an active modality session, the image will not be deleted from the modality session. This will be done by the Modality API when the session is ended.

Responses

204 Successfully deleted resource

404 Image resource not found

Get Image Media

GET/images/{id}/media

This method returns the media associated with an image resource.

Authorization

BasicAuth

Path Parameters

Parameter Type Required? Description
sessionId string Yes The session id
imageId string Yes The image id

Responses

200 Success

404 Session or image not found

Response schema: image/*

The body of a successful response will contain binary data in the format defined by the Content Type header (typically, image/png).

Models

To reduce the repetition of long descriptions in the documentation, complex objects are collected in this section.

ImageResource

Name Type Description
id string The resource id associated with the image
mediaType string The media type describing the format of the image data
url string The Url where the media resource can be downloaded
createdOn string Timestamp indicating when the resource was created
expires string Timestamp indicating when the resource will expire automatically and be deleted
imageInfo object (ImageInfo) Describes information about the image used to create an ImageResource. This information should be obtained directly from the corresponding ImageInfo object of the image acquired using the DSIO Modality API. Note that this object is a subset of the DSIO Modality API, thus allowing API consumers to use the same object for both.
modalitySession object (ModalitySession) Optional object that when present indicates that the resource belongs to a session created with the Modality API.

Back to Create Image Resource or Create Modality Resource or Get Image Resource

ImageInfo

Name Type Description
acquisitionInfo object Describes information regarding the acquisition from the DSIO Modality API.
>binning string The binning mode used to acquire the image. Enum: Binned2x2 - Combines pixels for a smaller file size image at lower resolution. When binning is set to Binned2x2 the sensor combines 4 pixels in a 2x2 neighborhood to create a single pixel. The resulting image is 1/4th the size of an Unbinned image, but with lower resolution. Unbinned - The operation of combining pixels to achieve smaller file images is not performed. Please note that acquiring images in either "binned" or "unbinned" mode is not a feature available for all sensors. Choosing these modes for sensors that do not support them will be ignored by the API.
lutInfo object The Url where the media resource can be downloaded
>gamma number (double) Gamma value used in map
>slope number (double) Slope value used in map
>offset number (double) Offset value used in map
>totalGrays number (integer) Total number of gray values in original (unmapped) image
>minimumGray number (integer) Minimum gray value in original (unmapped) image
>maximumGray number (integer) Maximum gray value in original (unmapped) image

Back to Create Image Resource or Create Modality Resource or Get Image Resource

ModalitySession

Name Type Description
sessionId string Id of modality session
imageId string Id of the image acquired by modality

Back to Create Image Resource or Create Modality Resource or Get Image Resource