Example: Create an Intersection Structure

[kyleburnett]

The example below shows how you can create an intersection structure using ProKnow's Python SDK. Please do no copy this code without making appropriate modifications and verifying that it is doing what you want it to do.

from proknow import ProKnow
import pyclipper

def convert_to_clipper(paths):
    cpaths = []
    for path in paths:
        cpath = []
        i = 0
        while i < len(path):
            cpath.append([path[i], path[i + 1]])
            i += 2
        cpaths.append(cpath)
    return cpaths

def convert_to_proknow(paths):
    ppaths = []
    for path in paths:
        ppath = []
        for pair in path:
            ppath.extend(pair)
        ppaths.append(ppath)
    return ppaths

pk = ProKnow('{base_url_here}', credentials_file="./credentials.json")
patient = pk.patients.find("{workspace_name}", mrn="{patient_mrn_here}").get()
entities = patient.find_entities(lambda entity: entity.data["type"] == "structure_set")
structure_set = entities[0].get()

# Find A and B structures
match_a = next((roi for roi in structure_set.rois if roi.name == "A"), None)
match_b = next((roi for roi in structure_set.rois if roi.name == "B"), None)

# Perform intersection
contours_A = match_a.get_data().contours
contours_B = match_b.get_data().contours
contours_C = []
for item in contours_A:
    slice_B = next((x for x in contours_B if x["pos"] == item["pos"]), None)
    if slice_B is not None:
        proknow_paths_A = item["paths"]
        proknow_paths_B = slice_B["paths"]
        clipper_paths_A = convert_to_clipper(proknow_paths_A)
        clipper_paths_B = convert_to_clipper(proknow_paths_B)
        # Perform clipping operation
        pc = pyclipper.Pyclipper()
        pc.AddPaths(clipper_paths_A, pyclipper.PT_SUBJECT, True)
        pc.AddPaths(clipper_paths_B, pyclipper.PT_CLIP, True)
        solution = pc.Execute(pyclipper.CT_INTERSECTION, pyclipper.PFT_NONZERO, pyclipper.PFT_NONZERO)
        solution = pyclipper.CleanPolygons(solution, 2)
        contours_C.append({
            "pos": item["pos"],
            "paths": convert_to_proknow(solution)
        })

# Create new structure C
with structure_set.draft() as draft:
    roi = draft.create_roi("C", [0, 255, 0], "ORGAN")
    data = roi.get_data()
    data.contours = contours_C
    data.save()
    # Commend this out if you want to commit the structure set as a new version
    # draft.approve()

Let's go through this file step-by-step to understand what's happening.

from proknow import ProKnow
import pyclipper

These are the import statements and assume that you have the packages proknow and pyclipper already installed with pip.

def convert_to_clipper(paths):
    cpaths = []
    for path in paths:
        cpath = []
        i = 0
        while i < len(path):
            cpath.append([path[i], path[i + 1]])
            i += 2
        cpaths.append(cpath)
    return cpaths

def convert_to_proknow(paths):
    ppaths = []
    for path in paths:
        ppath = []
        for pair in path:
            ppath.extend(pair)
        ppaths.append(ppath)
    return ppaths

These functions are responsible for converting ProKnow contour paths to clipper paths and vice versa.

pk = ProKnow('{base_url_here}', credentials_file="./credentials.json")

This line creates an instance of the ProKnow class. Note that you will need to replace {base_url_here} with the base URL of your ProKnow organization.

patient = pk.patients.find("{workspace_name}", mrn="{patient_mrn}").get()

This statement finds a patient and gets the patient details (e.g., its studies and entities). {workspace_name} and {patient_mrn} should be replaced with the values for a patient with a structure set containing structures you want to intersect.

entities = patient.find_entities(lambda entity: entity.data["type"] == "structure_set")
structure_set = entities[0].get()

These statements find all structure set entities and gets the details for the first one in the list.

match_a = next((roi for roi in structure_set.rois if roi.name == "A"), None)
match_b = next((roi for roi in structure_set.rois if roi.name == "B"), None)

These lines are responsible for finding structures we want to intersect by name.

contours_A = match_a.get_data().contours
contours_B = match_b.get_data().contours
contours_C = []

These lines extract the contour data for the two input structures and creates an empty array to hold the contours for the resulting intersection structure.

for item in contours_A:
    slice_B = next((x for x in contours_B if x["pos"] == item["pos"]), None)

These lines loop through the slices with contours for structure "A" and attempts to find a slice at the same position in structure "B".

    if slice_B is not None:
        proknow_paths_A = item["paths"]
        proknow_paths_B = slice_B["paths"]
        clipper_paths_A = convert_to_clipper(proknow_paths_A)
        clipper_paths_B = convert_to_clipper(proknow_paths_B)

Since this is an intersection operation, we only consider slices in which there are contours defined for both structures on the same slice, which is what the if condition ensures. The next four lines extract the paths from the dictionary object and convert the paths to a form that clipper can use.

        pc = pyclipper.Pyclipper()
        pc.AddPaths(clipper_paths_A, pyclipper.PT_SUBJECT, True)
        pc.AddPaths(clipper_paths_B, pyclipper.PT_CLIP, True)
        solution = pc.Execute(pyclipper.CT_INTERSECTION, pyclipper.PFT_NONZERO, pyclipper.PFT_NONZERO)
        solution = pyclipper.CleanPolygons(solution, 2)
        contours_C.append({
            "pos": item["pos"],
            "paths": convert_to_proknow(solution)
        })

These lines perform the clipping operation by (a) creating a new Pyclipper instance, (b) adding the clip and subject paths, and (c) executing the intersection operation. Before appending to the contour slices array, the contour points are cleaned to removing artifacts (using a distance of 2 units, i.e., 0.002 mm).

with structure_set.draft() as draft:

This line creates a draft of the structure set or opens the existing draft if it already exists, automatically renewing the current user's claim on the draft. When the interpreter exists the with block, the claim will be automatically released if applicable.

    roi = draft.create_roi("C", [0, 255, 0], "ORGAN")

This line creates a new ROI on the draft. It is given the name "C," the color green, and a type of "ORGAN."

    data = roi.get_data()
    data.contours = contours_C
    data.save()

These lines overwrites the default, empty contours array with the contours that represent the intersection of contours "A" and "B." Then the data is saved.

[liam-stubbington]

@kyleburnett - thanks for working through this example, much apprecaited. I will see if I can figure out the union operation.