Allow loading user defined treatment machines in Room's Eye View

[cpinter]

Many times researchers would like to calculate collisions for their machines but they cannot share the treatment machine models. At the same time they would be willing to define the parts if there was a relatively convenient way to do so.

This could be achieved by defining a JSON schema that describes the parts. The currently available treatment machines should be converted to this new method as well. A separate repository could be set up for the publicly available machine definitions.

A project with @ferdymercury

[MichaelColonel]

You can count on me, if you need help with models transform programming and other stuff!

[cpinter]

Thank you :)

[cpinter]

Working on a sample JSON file to describe the existing Varian machine. This is what I have now. Please comment on anything that could need to be added or changed:

{
  "TreatmentMachineName": "Varian TrueBeam STx",
  "$schema": "https://raw.githubusercontent.com/???/???-schema.json#",
  "Part": [
    {
      "Type": "Collimator",
      "File": "Collimator.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ]
    },
    {
      "Type": "Gantry",
      "File": "Gantry.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ]
    },
    {
      "Type": "ImagingPanelLeft",
      "File": "ImagingPanelLeft.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ]
    },
    {
      "Type": "ImagingPanelRight",
      "File": "ImagingPanelRight.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ]
    },
    {
      "Type": "LinacBody",
      "File": "LinacBody.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ]
    },
    {
      "Type": "PatientSupport",
      "File": "PatientSupport.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ]
    },
    {
      "Type": "TableTop",
      "File": "TableTop.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ]
    },
  ]
}

One thing that made me thinking is that the movement of the imaging panels is more complex than a simple translation or rotation (first rotates in then starts to translate too). After checking, actually, it seems that the movement of the panels is broken. It seems out of scope for this project to fix that I guess (I may still do it), but certainly worth mentioning that there are some magic numbers in the code that moves the imaging panels, and also worth considering if we want to load that parameter from JSON as well:

SlicerRT/RoomsEyeView/Logic/vtkSlicerRoomsEyeViewModuleLogic.cxx

Lines 1030 to 1037 in 19572b5

	if (panelMovement > 0)
	{
	rasToRotatedRasTransform->RotateZ(68.5);
	}
	else
	{
	rasToRotatedRasTransform->RotateZ(panelMovement + 68.5);
	}

[ferdymercury]

Looks very good, thanks for your work!

Some comments below:

• An optional "Color" tag (in HEX or RGB) for each subpart could be helpful, in case there is the option to override the one from the STL upon loading.
• A "visible" or "active" tag could be also helpful, in the sense that maybe when you commission the JSON file, you have all the parts included, but then for speedup reasons you might want always to hide the patient support that never leads to collisions, so instead of removing that part from the INI file, you just point to deactivate it without having to delete potentially future useful info.
• A human-readable "Title" tag could be added, which would be useful to later say, there was a collision with the "Gantry head" and the "Patient support", rather than between "PatientSupport" and "Gantry" as specified in the Type tag, that I guess will map to an enum rather than a string.
• Maybe it is useful to add a tag "Instructions" onto this file, that details (among other things) that files should be given in the IEC? frame of reference, or if not, specified otherwise in the FileToPartTransformMatrix. This way, people could just download an "example" json file and modify to their needs in a text editor, following those in-place instructions. Or would it be better to separate the instructions to a different place (a README.md in the repo or sth like that?).
• Optional "Author", "Date" and "Source" tags could be useful to locate the source of this machine or who modeled it. For example "Author": "Eduardo Meilán Bermejo", "Date":"2017" , "Source" : "github.com/SlicerRt/3Drepo"}
• An additional tag "Folder" could be added at the top, that can be either empty (or "./"), or instead pointing to the full path where the files are stored. So that, if one later moves the folder somewhere else, one can just change that line, and not all the other ones of each part, that are relative to that parent folder.
• Optionally, the Folder could be also a URL if the data are stored somewhere online rather than locally ? If this makes things too complicated, let's leave it.
• As far as I understand, the "Type" tag is associated with a given internal logic in slicer that controls the degrees of freedom. For example, if it's a couch, then we are allowing XYZ and azimuthal freedom, if it's a gantry, we only allow polar rotation but no translation. I am wondering if it would be to internally doable to represent this information in terms of this list of degrees of freedom rather than / or in addition to / Types. This is how I had implemented it for RayStation, see https://github.com/mghro/rad-collision/blob/08a29e0250e2243989d4eda2699b7c1c6aabc76e/RayStation/collision_detection.py#L148 The rationale for this is in the next point:
• Some gantries only allow gantry angles from 0 to 190 or so. It would be nice if the JSON file had a tag to describe the maximum motion range, and this info is forwarded later to the GUI sliders. The same happens with the couch, you cannot infinitely move in Z. Thus, I was thinking it would be helpful to have tags like: "DegreesOfFreedom": { "X": [-100,100], "Y":[-100,100], "Phi":[0,190deg]} for each the parts defined. I guess the "Type" tag should be used to cross-check for consistency, and warn the user if he is using a DOF that does not exist for that Type-Part in the internal SlicerRt logic. Or maybe we could even have a "Generic" Type that does not preassume any constraint, and is only defined by the "DOF" in the file.
• Yes, the panel rotation, although it's not something I'm directly interested in, could be also parameterized via the JSON file to remove any hard-coded magic numbers :) .
• Do we want to optionally allow defining multiple machines inside the same JSON file? The different treatment machine names would then be loaded to the dropdown dialog and one can later switch easily among them.
• Would it be helpful to add a security feature? Saying at the top "MaximumSizePerPart": 100Mb, "TotalMaximumSize": 1Gb, so that SlicerRt does not load those STL files if these constraints are not constrained in the currently free memory? But maybe it's a bit of overkill.

[cpinter]

Thanks for the comments! Good that you have more ideas now seeing this file - I only added those that we defined at our meeting. A few things:

• There is no good way to have enum in JSON (at least I did an extensive search yesterday and this was the conclusion), so it needs to be something we check in C++ whether the string used for Type is among the accepted ones or not.
• I'd probably add the instructions in the README.md of the repository where we have the publically available machines
• Indicating author is a good idea, although I wouldn't add URLs pointing to its own repository in the JSON
• Folder: I'd rather just have it in the File. Maybe rename it to FilePath?
• Degrees of freedom: Yes this could be very useful. I'd suggest we add this after the first simple approach works
• Multiple machines in one JSON: I don't see the rationale. It puts a development burden on us, when for the user it would be a minor technicality and maybe 10s of extra work to save it in two files instead of one. Also cleaner to have one JSON for each machine in every sense I can think of
• The file size limit would make more sense in the C++ logic I think, because I don't see a reason for having it different for each machine. But this also seems like a feature we can add later

Here's the updated sample JSON file. I changed some element names to be more unambiguous (title vs name, active vs visible vs enabled):

{
  "TreatmentMachineName": "Varian TrueBeam STx",
  "$schema": "https://raw.githubusercontent.com/???/???-schema.json#",
  "Part": [
    {
      "Type": "Collimator",
      "Name": "Collimator",
      "FilePath": "Collimator.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ],
      "Color": [255, 255, 255],
      "Enabled": true
    },
    {
      "Type": "Gantry",
      "Name": "Gantry",
      "FilePath": "Gantry.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ],
      "Color": [255, 255, 255],
      "Enabled": true
    },
    {
      "Type": "ImagingPanelLeft",
      "Name": "Left imaging panel",
      "FilePath": "ImagingPanelLeft.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ],
      "Color": [255, 255, 255],
      "Enabled": true
    },
    {
      "Type": "ImagingPanelRight",
      "Name": "Right imaging panel",
      "FilePath": "ImagingPanelRight.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ],
      "Color": [255, 255, 255],
      "Enabled": true
    },
    {
      "Type": "LinacBody",
      "Name": "Linac body",
      "FilePath": "LinacBody.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ],
      "Color": [255, 255, 255],
      "Enabled": true
    },
    {
      "Type": "PatientSupport",
      "Name": "Patient support",
      "FilePath": "PatientSupport.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ],
      "Color": [255, 255, 255],
      "Enabled": true
    },
    {
      "Type": "TableTop",
      "Name": "Table top",
      "FilePath": "TableTop.stl",
      "FileToPartTransformMatrix": [ [1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1] ],
      "Color": [255, 255, 255],
      "Enabled": true
    }
  ]
}

[ferdymercury]

• There is no good way to have enum in JSON (at least I did an extensive search yesterday and this was the conclusion), so it needs to be something we check in C++ whether the string used for Type is among the accepted ones or not.

Sounds good.

• I'd probably add the instructions in the README.md of the repository where we have the publically available machines

Perfect.

• Indicating author is a good idea, although I wouldn't add URLs pointing to its own repository in the JSON

Agreed.

• Folder: I'd rather just have it in the File. Maybe rename it to FilePath?

Good idea, too.

• Degrees of freedom: Yes this could be very useful. I'd suggest we add this after the first simple approach works

Great.

• Multiple machines in one JSON: I don't see the rationale. It puts a development burden on us, when for the user it would be a minor technicality and maybe 10s of extra work to save it in two files instead of one. Also cleaner to have one JSON for each machine in every sense I can think of

You're right.

• The file size limit would make more sense in the C++ logic I think, because I don't see a reason for having it different for each machine. But this also seems like a feature we can add later

Perfect.

Thanks so much :)

[cpinter]

The basic loading of treatment machine from JSON descriptor file works now for the default Varian TrueBeam machine.
Next steps are implementing color, enabled state, and the transform.

One question I have is what to do with the user interface. So far there has been a combobox with the two default machines. For now, as the easiest solution, I added a third option "From file...", clicking on which a file selector pops up and we can load the machine using that:

@ferdymercury @gregsharp what do you think the ideal GUI would look like for machine selection?

[cpinter]

@ferdymercury Also an idea as I was thinking about the Enabled state. I can imagine you want to show the model but not include it in the collision detection (also for speedup reasons). Should we include this somehow?