Skip to content

User guide

Circles

POST: /get_etdrs

Description

Builds the ETDRS circle (6mm diameter circle with 3 groups of segments: 1 central (1mm zone), 4 segments (1-3mm zone), 4 segments (3-6mm zone)) for the retinal layers thickness map.

Parameters:

Name Type Description Default
thickness_map list

Examination thickness map. Usually has shape of [num_slices, slice_width].

 required
layers list

list of layers which would be encountered in ETDRS circle calculation. Layers available: ["rnfl", "gcl", "ipl", "inl", "opl", "onl", "elm", "mz", "ez", "os", "rpe"]

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
statistics list

Statistics which should be calculated for each segment. Statistics available: ["mean", "std"]

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
statistics dict

statistics per each segment in format:

{0: {0: {'mean': <float>}}, 1: {0: {...}, 1: {...}, 2: {...}, 3: {...}}, ...}

POST: /get_gcc_circle

Description

Builds the GCC circle (6mm diameter circle with 2 groups of segments: 1 central (1mm zone), 6 segments (1-6mm zone)) for the retinal layers thickness map.

Parameters:

Name Type Description Default
thickness_map list

Examination thickness map. Usually has shape of [num_slices, slice_width].

 required
layers list

list of layers which would be encountered in ETDRS circle calculation. Layers available: ["rnfl", "gcl", "ipl", "inl", "opl", "onl", "elm", "mz", "ez", "os", "rpe"]

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
statistics list

Statistics which should be calculated for each segment. Statistics available: ["mean", "std"]

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
statistics dict

statistics per each segment in format:

{0: {0: {'mean': <float>}}, 1: {0: {...}, 1: {...}, 2: {...}, 3: {...}}, ...}

Fovea center, fovea and nerve zones

POST: /extract_center_n_fovea

Full pipeline with fovea zone extraction and center detection.

Works in the following way:

  1. Tries to find the fovea zone and the center within it. If successful, returns the result.

  2. If previous step fails, tries to find the center in the whole examination by finding the most probable point to be the center. If found point fits the 6mm circle, returns the result. The fovea zone is considered to be within 1mm from the center. Landmarks are not returned in this case.

  3. If previous step fails, tries to locate the probable center with respect to the nerve zone center (4.5 mm left/right from nerve zone center). Slice number is n/2. If found point fits the 6mm circle, returns the result. The fovea zone is considered to be within 1mm from the center. Landmarks are not returned in this case.

  4. Else returns "not_found" with [w/2, n/2] as the center of the examination.

Args:

    center_probabilities (list)   -- "is_center" model output, probabilities that given slices contain center
    fovea_probabilities (list)    -- "is_fovea" model_output, probabilities that the given slices contain fovea pit
    indices (list)                -- list of slice indices for which the coordinate belongs (to preserve the order of slices in the examination)
    coordinates (list)            -- landamrk_coordinates
    landmark_probabilities (list) -- landmark_existance_prob

    fovea_existance_threshold (float, Optional)           -- threshold for fovea zone existence, default 0.5
    fovea_landmark_existance_threshold (float, Optional)  -- threshold for landmark existence, default 0.35
    fovea_min_number_of_sequential_slices (int, Optional) -- minimum number of sequential slices to consider the fovea zone, default 2
    fovea_connectivity_level (int, Optional)              -- connectivity level for the fovea zone, default 3

    nerve_zone (dict, Optional)                 -- result of the nerve zone extraction from extract_nerve_zone_landmarks

    num_slices (int)                            -- number of slices in exam
    img_height (int)                            -- image pixel height
    img_width (int)                             -- image pixel width
    slice_thickness (float)                     -- slice thickness in mm
    pixel_spacing_column (float)                -- pixel spacing column from DICOM metadata
    scan_width (int)                            -- scan width in mm
    scan_height (int)                           -- scan height in mm
    eps (float, Optional)                       -- epsilon, default 0.05
    nerve_scan_size_threshold (float, Optional) -- starting from which scan size we need to use nerve based center search logic. Defaults to 9 mm.
    scan_protocol (str)                         -- scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

Returns:

Name Type Description
JSON dict

the most probable point to be a center of the examination in the following format:

{
    "status":                   "found_full" / "found_center" / "found_nerve_based_center" / "not_found" / "found_central_slice_only"
    "fovea_zone_slice_indices": list of slice indices for which the fovea zone was detected
    "central_slice_index":      index of the central slice
    "fovea_zone_landmarks":     list of fovea zone landmarks (len(fovea_zone_slice_indices) x 3 x 2)
    "exam_center_coordinate":   center of the examination in the enface view, [w, n]
}

POST: /extract_nerve_zone_landmarks

Nerve zone detection.

Optional parameters are made to make fast changes possible, already set by ML team by default.

Args:

nerve_probabilities (list)    -- "has_nerve" model output, probabilities that given slices contain nerve zone
indices (list)                -- list of slice indices for which the coordinate belongs (to preserve the order of slices in the examination)
coordinates (list)            -- landamrk_coordinates
landmark_probabilities (list) -- landmark_existance_prob

nerve_existance_threshold (float, Optional)           -- threshold for nerve zone existence, default 0.3
nerve_confidence_threshold (float, Optional)          -- threshold for nerve zone confidence, default 0.65
nerve_landmark_existance_threshold (float, Optional)  -- threshold for landmark existence, default 0.3
nerve_min_number_of_sequential_slices (int, Optional) -- minimum number of sequential slices to consider the nerve zone, default 2
nerve_connectivity_level (int, Optional)              -- connectivity level for the nerve zone, default 3

Returns:

Name Type Description
JSON dict

the most probable point to be a center of the examination in the following format:

{
    "status":                   "found" / "not_found" (no info returned in this case)
    "nerve_slice_indices":      list of slice indices for which the nerve zone was detected
    "nerve_zone_landmarks":     list of nerve zone landmarks (len(nerve_slice_indices) x 3 x 2)
}

Glaucoma

POST: /get_two_segment_circle

Description

Calculates superior and inferior thicknesses of the retina by its layers. Returns Superior and Inferior parts thicknesses in µm.

Parameters:

Name Type Description Default
thickness_map dict

layers thickness map (returned from /get_thickness_map)

 required
layers list

layers to examine (optional, [“rnfl”, “gcl”, “ipl”] by default)

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Type Description

JSON dict: superior and inferior thicknesses of the retina in µm

{
    "superior_thickness": float,
    "inferior_thickness": float
}

POST: /get_four_segment_circle

Description

Calculates thickness statistics for each element of four segment glaucoma circle.

Parameters:

Name Type Description Default
thickness_map dict

layers thickness map (returned from /get_thickness_map)

 required
layers list

layers to examine (optional, [“rnfl”, “gcl”, “ipl”] by default)

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
statistics_to_get list

Statistics which should be calculated for each segment. Statistics available: ["mean", "std"].

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
statistics dict

statistics per each segment in µm

POST: /get_full_exam_glaucoma_ppaa_matrix

Description

Calculates PPAA matrix for superior and inferior retina parts for full zone of retina.

Parameters:

Name Type Description Default
thickness_map dict

layers thickness map (returned from /get_thickness_map)

 required
layers list, optional, default=[“rnfl”, “gcl”, “ipl”]

layers to examine

 required
metadata dict

separate field in json, containing the parameters below:

  • use_real_units (bool): whether to use real units in thickness map calculation. if False -- pixel units are used.

  • pixel_spacing_row (float): Pixel spacing row from DICOM metadata. Should be specified if use_real_units==True.

 required

Returns:

Type Description

JSON dict in the following format:

{
    "ppaa": [list, 8x8 PPAA matrix]
}

POST: /get_mmzone_glaucoma_ppaa_matrix

Description

Calculates PPAA matrix for superior and inferior retina parts for defined zone of retina.

More detailed description here: https://media.heidelbergengineering.com/uploads/Products-Downloads/99172-001_SPECTRALIS_Brochure_Posterior-Pole-Insert_EN.pdf

Parameters:

Name Type Description Default
thickness_map dict

layers thickness map (returned from /get_thickness_map)

 required
layers list, optional, default=[“rnfl”, “gcl”, “ipl”]

layers to examine

 required
zone_of_search float, optional, default=6.0

retina zone region in mm which will be used to build the PPAA

 required
metadata dict

separate field in json, containing the parameters below:

  • pixel_spacing_row (float): Pixel spacing row from DICOM metadata.

  • pixel_spacing_column (float): Pixel spacing column from DICOM metadata.

  • slice_thickness (float): Slice thickness from DICOM metadata.

  • scan_protocol (str): scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".
  • slice_direction (str): slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol
  • pixel_direction (str): pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol
 required

Returns:

Type Description

JSON dict in the following format:

{
    "ppaa": [list, 8x8 PPAA matrix],
    "status": OK | PPAA_NOT_CALCULATED_NEGATIVE_STRIDE (code 415)
}

POST: /get_glaucoma_stage

Description

Calculates the probable stage of glaucoma.

Parameters:

Name Type Description Default
thickness_s float

superior part thickness in µm (from /get_two_segment_circle)

 required
thickness_i float

inferior part thickness in µm (from /get_two_segment_circle)

 required

Returns:

Type Description

JSON dict in the following format:

{
    "stage": 'GREEN' | 'YELLOW' | 'ORANGE | 'RED',
    "status": OK | ONE_OF_THICKNESSES_OUT_OF_BOUNDARIES_OF_THICKNESS_MAXIMUM (code 415)
}

POST: /get_glaucoma_distance_to_normal

Description

Calculates the examination “distance” from normal in terms of glaucoma. 0 means healthy retina, 1 -- glaucoma. Needed for green-yellow-red slider on glaucoma page.

Parameters:

Name Type Description Default
thickness_s float

superior part thickness in µm (from /get_two_segment_circle)

 required
thickness_i float

inferior part thickness in µm (from /get_two_segment_circle)

 required

Returns:

Type Description

JSON dict in the following format:

{
    "stage": <float between 0.0 and 1.0>,
    "status": OK | ONE_OF_THICKNESSES_OUT_OF_BOUNDARIES_OF_THICKNESS_MAXIMUM (code 415)
}

Measurements

POST: /get_linear_calculations

Description

Calculates linear measurements for the pathologies in a single slice of examination.

Parameters:

Name Type Description Default
pathologies list

List of outputs from pathology segmentation model, containing segmentation instances for every pathology for a single slice in the following format:

[
    {"points": [], "className": "", ...},
    ...,
    {"points": [], "className": "", ...}
]
required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required

Returns:

Name Type Description
linear_measurements list <float>

[list of floats for every instance in pathologies list]

POST: /get_distance_between_two_points

Description

Caluclates distance between two points on a slice of examination.

Parameters:

Name Type Description Default
p1 list

[x, y] coordinate of point 1

 required
p2 list

[x, y] coordinate of point 2

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required

Returns:

Name Type Description
distance float

distance in real units, mm

POST: /get_area_calculations

Description

Calculates areas of pathologies per slice or on thickness map (enface view). There are 2 methods for pathology area calculation: polygon_area and mask_area. polygon_area is not allowed for pathology thickness in slice-width view (slice_thickness is None)

Parameters:

Name Type Description Default
pathologies dict or list

dict of pathologies thickness maps or list of instances.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float, optional, default=None

Pixel spacing row from DICOM metadata. Necessary for slice view area calculations.

 required
slice_thickness float, optional, default=None

Slice thickness from DICOM metadata. Necessary for enface view area calculations.

 required
area_method str, optional, default="polygon_area"

method for area calculation. One of ["polygon_area", "mask_area"].

 required
img_height int

image pixel height.

 required
img_width int

image pixel width.

 required

Returns:

Name Type Description
areas dict

areas for each pathology name in mm^2 in the following format:

{
    {"pathology_name_1": float},
    ...
    {"pathology_name_n": float}
}

POST: /get_volume_calculations

Description

Calculates pathology volume by enface view thickness map.

Parameters:

Name Type Description Default
pathologies dict

dict of pathologies thickness maps.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required

Returns:

Name Type Description
volumes dict

dict of calculated volumes for each pathology in mm3 in the following format:

{
    {"pathology_name_1": float},
    ...
    {"pathology_name_n": float}
}

Pathology specific

POST: /get_pathology_volume_etdrs_calculations

Description

Calculates the ETDRS circle based on pathology volume, for levels of the ETDRS circle.

Parameters:

Name Type Description Default
pathologies dict

dict of pathologies thickness maps.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
is_cumulative bool

whether to calculate ETDRS values in cumulative mode (1mm / 1mm + 3mm / 1mm + 3mm + 6mm zones values).

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
volumes dict

volumes per each segment in format in mm^3:

{
    "pathology_name_1": {0: <float>, 1: <float>, 2: <float>},
    ...,
    "pathology_name_n": {0: <float>, 1: <float>, 2: <float>},
}

POST: /get_pathology_area_etdrs_calculations

Description

Calculates the ETDRS circle based on pathology area, for levels of the ETDRS circle.

Parameters:

Name Type Description Default
pathologies dict

dict of pathologies thickness maps.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
img_height int

image pixel height.

 required
img_width int

image pixel width.

 required
is_cumulative bool

whether to calculate ETDRS values in cumulative mode (1mm / 1mm + 3mm / 1mm + 3mm + 6mm zones values).

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
areas dict

areas per each segment in format in mm^2:

{
    "pathology_name_1": {0: <float>, 1: <float>, 2: <float>},
    ...,
    "pathology_name_n": {0: <float>, 1: <float>, 2: <float>},
}

POST: /get_pathology_volume_etdrs_calculations_zone

Description

Calculates the ETDRS circle based on pathology volume, per ETDRS segment.

Parameters:

Name Type Description Default
pathologies dict

dict of pathologies thickness maps.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
volumes dict

volumes per each segment in format in mm^3:

{
    "pathology_name_1": statistics per each segment, as in /get_etdrs,
    ...,
    "pathology_name_n": statistics per each segment, as in /get_etdrs,
}

POST: /get_pathology_area_etdrs_calculations_zone

Description

Calculates the ETDRS circle based on pathology area, per ETDRS segment.

Parameters:

Name Type Description Default
pathologies dict

dict of pathologies thickness maps.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
img_height int

image pixel height.

 required
img_width int

image pixel width.

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
areas dict

areas per each segment in format in mm^2:

{
    "pathology_name_1": statistics per each segment, as in /get_etdrs,
    ...,
    "pathology_name_n": statistics per each segment, as in /get_etdrs,
}

POST: /get_maximal_pathology_slice_index_from_thm

Description

Calculates the maximal presence on the thickness map for each pathology. Returns the slice index with the maximal presence.

Parameters:

Name Type Description Default
pathologies dict

dict of pathologies thickness maps in pixel units.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
center_coordinates list

The center coordinates [x, y] for cropping.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required

Returns:

Name Type Description
max_pathologies dict

maximal presence of pathologies in format:

{
    "pathology_name_1": int,
    ...,
    "pathology_name_n": int,

}

Thickness map

POST: /get_thickness_map

Description

Builds the thickness map given the retinal segmentation model results. Returns thickness_map and one of statuses: "OK": thickness_map is created successfully and fits into the zone of interest "ZONE_OF_INTEREST_OUT_OF_SCAN_ZONE": thickness_map is created successfully, but zone of interest is bigger than scanning zone

Parameters:

Name Type Description Default
masks list

list of outputs from retinal layers segmentation model, containing segmentation instances for every layer, for every slice (length of list equals amount of scans in examination).

[
    {"instances": [{"points": [], "className": "", ...}, ...]},
    ...,
    {"instances": [{"points": [], "className": "", ...}, ...]}
]
required
metadata dict

metadata from DICOM that contains: - distance_method (str, default="axial"): "axial" (faster, finds distance between layer borders within a column) or "min_dist" (slower, finds the shortest distance between the layer borders per each column). - scan_protocol (str): scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D". - slice_direction (str): slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol - pixel_direction (str): pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol - run_resolution (int): resolution of the image to which the input image should be resized. Default is 512. - height (int): height of the image. - width (int): width of the image. - center_coordinates (list): coordinates of central scan. Should be a list of 2 elements [scan_x_coordinate, central_slice_number]. - pixel_spacing_column (float): Pixel spacing column from DICOM metadata. - slice_thickness (float): Slice thickness from DICOM metadata. - zone_of_interest (float): Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required

Returns:

Name Type Description
thickness_map dict

thickness maps for each layer in pixel units in the following format:

{
    "thickness_map": {
        "layer_1": [num_slices, img_width],
    ...
        "layer_n": [num_slices, img_width]
    }
    "status": "OK" / "ZONE_OF_INTEREST_OUT_OF_SCAN_ZONE"

}

POST: /get_pathology_thickness_map

Description

Builds the thickness map given the pathology segmentation model results. Returns thickness_map and one of statuses: "OK": thickness_map is created successfully and fits into the zone of interest "ZONE_OF_INTEREST_OUT_OF_SCAN_ZONE": thickness_map is created successfully, but zone of interest is bigger than scanning zone "NO_THICKNESS_MAPS": no thickness maps were created (no pathology instances were found in the examination)

Parameters:

Name Type Description Default
masks list

list of outputs from pathogy segmentation model, containing segmentation instances for every pathology, for every slice (length of list equals amount of scans in examination).

[
    {"instances": [{"points": [], "className": "", ...}, ...]},
    ...,
    {"instances": [{"points": [], "className": "", ...}, ...]}
]
required
pathologies list

list of pathology classes that should be used for thickness map calculations.

 required
metadata dict

metadata from DICOM that contains:

  • use_real_units (bool): whether to use real units in thickness map calculation. if False -- pixel units are used.

  • pixel_spacing_row (float): Pixel spacing row from DICOM metadata. Should be specified if use_real_units==True.

  • scan_protocol (str): scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".
  • slice_direction (str): slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol
  • pixel_direction (str): pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol
  • run_resolution (int): resolution of the image to which the input image should be resized. Default is 512.
  • height (int): height of the image.
  • width (int): width of the image.
  • center_coordinates (list): coordinates of central scan. Should be a list of 2 elements [scan_x_coordinate, central_slice_number].
  • pixel_spacing_column (float): Pixel spacing column from DICOM metadata.
  • slice_thickness (float): Slice thickness from DICOM metadata.
  • zone_of_interest (float): Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.
 required

Returns:

Name Type Description
JSON dict

thickness maps for each pathology specified in pathologies in pixel/real units in the following format:

{
    "pathology_name_1": [num_slices, img_width],
    ...
    "pathology_name_n": [num_slices, img_width],
    "status": "OK" / "ZONE_OF_INTEREST_OUT_OF_SCAN_ZONE" / "NO_THICKNESS_MAPS"
}

GA measurements

POST: /get_ga_thickness_map

Description

Finds the overlap between the given pathologies (given their thickness maps) that make up the GA region.

Parameters:

Name Type Description Default
pathology_thickness_maps list

list of pathologies thickness maps | the shape is (num_pathologies, num_slices, exam_width)

 required

Returns:

Name Type Description
ga_thickness_map dict

overlap between pathologies that make up the GA region:

{
    "ga_thickness_map": list
}

POST: /get_ga_circle_overlap_ratios

Description

Calculates percentage of the circle area covered by GA. The ratio is calculated for 1, 3 and 6 mm circles.

Parameters:

Name Type Description Default
ga_thickness_map list

GA thickness map from get_ga_thickness_map | the shape is (num_slices, exam_width)

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Type Description
dict

percentage of the area of each circle covered by GA:

{
    "1mm": float,
    "3mm": float,
    "6mm": float
}

POST: /get_ga_distance_to_fovea_center

Description

Finds minimal distance from GA region to fovea center.

Parameters:

Name Type Description Default
ga_thickness_map list

GA thickness map from get_ga_thickness_map | the shape is (num_slices, exam_width)

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
distance_to_fovea_center float

distance from GA region to fovea center in mm
nearest_point list

coordinates of the point which is nearest to the GA region { "distance_to_fovea_center": float, "nearest_point": list }

ODN analysis

POST: /extract_neuroretinal_rim_circles

Description

Extracts neuroretinal rim (disc and cup) from optic disc nerve in px. Processes geometry for each slice using landmarks of bruch's membrane opening and ILM layer for further circles extraction.

Length of nerve_landmarks_list, nerve_slices and ilm_list should be the same. Results in nerve_landmarks_list and ilm_list should correspond to the order in nerve_slices. If ilm cannot be extracted from the model, empy list should be sent for this idx.

disc and cup contain coordinates of polygon points. Cup polygon may be empty in case of excavation absence, minimal amount of points for further processing is 4.

disc and cup are returned both in mm and in px for visualization. Polygons for visualization are created based on scanning zone size and scalling factor. It is done to reduse artifacts due to small resolutions.

Parameters:

Name Type Description Default
nerve_landmarks_list list

list of nerve landmarks from landmark (fovea) model.

 required
nerve_slices list

list of slices where nerve is present from landmark (fovea) model.

 required
ilm_list list

list of ILM layers from retinal layer segmentation model.

 required
pixel_spacing_row float

Pixel spacing row from DICOM metadata.

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
ellipse_preprocessing bool, optional, default=True

If preprocessing via ellipse fitting is on or raw circles should be returned.

 required
fill_absent_slices bool, optional, default=True

If preprocessing via absent slices filling is on or raw circles will be returned.

 required
smooth_circles bool, optional, default=True

if disc and cup polygons smoothing should be used.

 required
d_mm (float, optional, 150 * 0.001)

distance for raising a parallel line in geometry processing. 150µm is used.

 required
scaling_factor_visualization (float, optional, 100.0)

what scaling will be used for pixel extraction, scaling is done based on scanning zone size.

 required
img_width int

width of the image

 required
num_slices int

amount of slices in the examination

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Type Description

JSON dict: disc and cup that form a neuroretinal rim. 

{
    "disk": list[n,2] in mm,
    "cup": list[m,2] in mm,
    "disk_viz": list[n,2] in px,
    "cup_viz": list[m,2] in px,
}

POST: /analyze_odn

Description

Analyzes optic disc based on neuroretinal rim's disc and cup. Linear, area calculations are conducted for disc, cup and rim. DDLS (disc damage likelyhood scale) analysis is performed for glaucoma stage assessment. DDLS analysis can be processed only if excavation is present, otherwise only disc parameters will be returned.

All calculated parameters are returned in mm/mm2. All points/lists of points for visualization are returned in px.

Parameters:

Name Type Description Default
disc list

list of points for disc, extracted from extract_neuroretinal_rim_circles in mm.

 required
cup list

list of points for cup, extracted from extract_neuroretinal_rim_circles in mm.

 required
scaling_factor_visualization (float, optional, 100.0)

what scaling will be used for pixel extraction, scaling is done based on scanning zone size.

 required

Returns:

Type Description

JSON dict: 

{
    "disk_area": area of disc, float in mm2
    "cup_area": area of cup, float in mm2
    "rim_area": area of rim, float in mm2
    "cup_disk_area": cup disc areas ratio, float
    "disk_size": size of the disc, str, one of [small, average, large],
    "odn_mass_center": nerve center of mass, list [1,2] in [x, y] format in px,
    "vertical_DD": vertical disc diameter, float in mm,
    "vertical_DD_line": vertical disc diameter line, list [2,2] in [x, y] format in px, for visualization,
    "horizontal_DD": horizontal disc diameter, float in mm,
    "horizontal_DD_line": horizontal disc diameter line, list [2,2] in [x, y] format in px, for visualization,
    "R": smallest rim width, DDLS analysis, float in mm,
    "R_line": line of R, DDLS analysis, list [2,2] in [x, y] format in px, for visualization,
    "D": disc diameter of the same axis as R, float in mm,
    "D_line": line of D, DDLS analysis, list [2,2] in [x, y] format in px, for visualization,
    "rim_disk_ratio": rim disc length ration, DDLS analysis, float,
    "rim_absence_angle": angle of sequential rim absence (R~0), float in angles, DDLS analysis,
    "rim_absence_sector": sector of rim absence, list [n,2] in [x, y] format in px, for visualization,
    "ddls_stage": stage of glaucoma based on DDLS analysis, int
}

Vessel Map

GET: /get_vessel_map

Description

Creates a vessel map / fundus-like image from examination sequential images.

Parameters:

Name Type Description Default
input_bucket str

Bucket name where examinations are stored.

 required
input_location str

Location in the input_bucket of the examination.

 required
input_bucket_cloud str, optional, default="gcp"

Cloud provider where the input_bucket is located. Can be either "gcp" or "azure_uae".

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
inpaint_artifacts bool, optional, default=True

If artifacts inpainting should be used.

 required
scaling_factor_visualization (float, optional, 100.0)

what scaling will be used for vessel map, scaling is done based on scanning zone size.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
vessel_map str

base64 image of shape (scanning zone width x scaling_factor_visualization, scanning zone height x scaling_factor_visualization)

GET: /get_vessel_map_img_space

Description

Creates a vessel map / fundus-like image from examination sequential images. Returns vessel map in image space (img width x num_slices) and one of statuses: "OK": vessel map is created successfully and fits into the zone of interest "ZONE_OF_INTEREST_OUT_OF_SCAN_ZONE": vessel map is created successfully, but zone of interest is bigger than scanning zone

Parameters:

Name Type Description Default
input_bucket str

Bucket name where examinations are stored.

 required
input_location str

Location in the input_bucket of the examination.

 required
input_bucket_cloud str, optional, default="gcp"

Cloud provider where the input_bucket is located. Can be either "gcp" or "azure_uae".

 required
inpaint_artifacts bool, optional, default=True

If artifacts inpainting should be used.

 required
scaling_factor_visualization (float, optional, 100.0)

what scaling will be used for vessel map, scaling is done based on scanning zone size.

 required
zone_of_interest float

Zone that will be cropped from the center of the thickness map. Default is 6.0 mm.

 required
center_coordinates list

coordinates of central scan. Should be a list of 2 elements [scan_x_coordinate, central_slice_number].

 required
pixel_spacing_column float

Pixel spacing column from DICOM metadata.

 required
slice_thickness float

Slice thickness from DICOM metadata.

 required
scan_protocol str

scanning protocol of the examination. Can be "HORIZONTAL_3D", "VERTICAL_3D".

 required
slice_direction str

slice direction of the examination. Can be "TOP_BOTTOM", "BOTTOM_TOP" for HORIZONTAL_3D protocol or "LEFT_RIGHT", "RIGHT_LEFT" for VERTICAL_3D protocol

 required
pixel_direction str

pixel direction of the examination. Can be "LEFT_RIGHT", "RIGHT_LEFT" for HORIZONTAL_3D protocol or "TOP_BOTTOM", "BOTTOM_TOP" for VERTICAL_3D protocol

 required

Returns:

Name Type Description
vessel_map list

2D list of vessel map in image space (img width x num_slices)
status

"OK" / "ZONE_OF_INTEREST_OUT_OF_SCAN_ZONE"