decimal App Documentation

User Tools

Site Tools

Trace:
dosimetry:userguide:design_task_functions:dtf

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
dosimetry:userguide:design_task_functions:dtf [2015/07/02 15:47] – [Range Compensator Design] dpatenaudedosimetry:userguide:design_task_functions:dtf [2021/07/29 18:28] (current) – external edit 127.0.0.1
Line 4: Line 4:
 ===== Aperture Design===== ===== Aperture Design=====
  
-Below is a list of the most common aperture design task function and a brief explanation of their intended usage (Specific details of each function, argument parameters, and return values are provided at the [[http://docs.dosimetry.dotdecimal.com|Dosimetry App Manifest Guide]]).+Below is a list of the most common aperture design task function and a brief explanation of their intended usage (Specific details of each function, argument parameters, and return values are provided at the [[http://docs.apps.dotdecimal.com|Dosimetry App Manifest Guide]]).
  
   * **compute_aperture:**   * **compute_aperture:**
     * Compute the aperture without smoothing.     * Compute the aperture without smoothing.
-    * Limits mill radius. If not specified to 4.7625mm (0.1875") or to be no smaller than 1.5875mm (0.0625"). +    * Recommended mill radius value is is 4.7625mm (0.1875") and advised to be no less than 2.38125mm (0.09375") to allow for accurate machining. 
-  * **compute_smooth_aperture:** +  * **compute_smoothed_aperture:** 
-    * Compute an aperture smoothed with a Guassian type blur on all targets and organs +    * Compute an aperture smoothed with a vertex shift on all targets and organs 
-    * Limits mill radius. If not specified to 4.7625mm (0.1875") or to be no smaller than 1.5875mm (0.0625").+    * Recommended mill radius value is is 4.7625mm (0.1875") and advised to be no less than 2.38125mm (0.09375") to allow for accurate machining.
   * **smooth_aperture:**   * **smooth_aperture:**
-    * Smooth an existing aperture with a Gaussian type blur.+    * Smooth an existing aperture with a vertex shift.
   * **get_field_rect:**   * **get_field_rect:**
     * Gets the bounding box (in BEV) for the aperture opening (at true size not projected).     * Gets the bounding box (in BEV) for the aperture opening (at true size not projected).
Line 22: Line 22:
   * **make_aperture:**   * **make_aperture:**
     * Builds an aperture using the given point list.     * Builds an aperture using the given point list.
-    * Limits mill radius. If not specified to 4.7625mm (0.1875") or to be no smaller than 1.5875mm (0.0625").+    * Recommended mill radius value is is 4.7625mm (0.1875") and advised to be no less than 2.38125mm (0.09375") to allow for accurate machining. 
 +  * **remove_polyset_holes:** 
 +    * A polyset's holes defined an aperture's floating islands. By removing the polyset holes, the resulting computed aperture will contain no islands. 
 +    * This function removes the holes from a polyset of an existing aperture (e.g.: Call compute_aperture() and using the polyset from the returned aperture call remove_polyset_holes(). Then replace the original aperture polyset with the polyset returned from remove_polyset_holes()) 
 +  * **apply_mill_radius:** 
 +    * This function applies a machinability enforcement using a tool mill radius to a polyset of an existing aperture. The resulting polyset shape will not have corners that produce machined under cutting for the mill radius defined.
 ==== Geometry ==== ==== Geometry ====
  
Line 29: Line 34:
 The aperture device is modeled as one or more open (i.e. the radiation can pass through the defined shape) or closed (i.e. the radiation cannot pass through the defined shape) contours. The actual device blocking is achieved by shaping a high density material, either milled or with a multi-leaf collimator. The contour shapes are modeled at their intended position Zb along the beam axis. The overall aperture is bounded by the mounting apparatus that holds the aperture (typically creating circular or rectangular bounding aperture shapes). The aperture device is modeled as one or more open (i.e. the radiation can pass through the defined shape) or closed (i.e. the radiation cannot pass through the defined shape) contours. The actual device blocking is achieved by shaping a high density material, either milled or with a multi-leaf collimator. The contour shapes are modeled at their intended position Zb along the beam axis. The overall aperture is bounded by the mounting apparatus that holds the aperture (typically creating circular or rectangular bounding aperture shapes).
  
-The contour shape is constrained by the ability to mechanically construct the shape. Milling will be assumed as the primary mode of construction, with a minimum mill tool radius of 0.0625 inches allowable, but 0.1875 inches is the standard default tool radius if none is specified.+The contour shape can be constrained by the ability to mechanically construct the shape. Milling can be assumed as the primary mode of construction, with a recommended mill radius value is is 4.7625mm (0.1875“) and advised to be no less than 2.38125mm (0.09375”) to allow for accurate machining. 
 + 
  
 Aperture beam-limiting devices have a physical thickness which is ignored in the beam model. Only the aperture opening shape is considered during any Dosimetry App calculations. Apertures are considered to be infinitely thin and thickness of the devices and slabs will be ignored for divergence and on/off blocking (See Slopsema). Aperture beam-limiting devices have a physical thickness which is ignored in the beam model. Only the aperture opening shape is considered during any Dosimetry App calculations. Apertures are considered to be infinitely thin and thickness of the devices and slabs will be ignored for divergence and on/off blocking (See Slopsema).
Line 36: Line 43:
 ==== Computing an Aperture Shape ==== ==== Computing an Aperture Shape ====
  
-This example will provide a high level walk through of calling the //compute_smooth_aperture// function (note //compute_aperture// is simply a reduced version of this function so this example applies equally to both functions). The code here is meant to be used as a guide on the process to follow and functions/data types to construct. The returned value is the computed geometric shape of the aperture (projected to the given downstream position) based on the arguments passed into the calculation request.+This example will provide a high level walk through of calling the //compute_smoothed_aperture// function (note //compute_aperture// is simply a reduced version of this function so this example applies equally to both functions). The code here is meant to be used as a guide on the process to follow and functions/data types to construct. The returned value is the computed geometric shape of the aperture (projected to the given downstream position) based on the arguments passed into the calculation request.
  
   - Construct a //beam_geometry//   - Construct a //beam_geometry//
Line 62: Line 69:
 ap_params.downstream_edge = 100.0; // Set the distance from patient side surface to isocenter along CAX (100mm) ap_params.downstream_edge = 100.0; // Set the distance from patient side surface to isocenter along CAX (100mm)
 </code> </code>
-  - The //aperture_creation_params// are then sent to the dosimetry app as calculation requests following [[userguide:thinknode|thinknode™ calculation request]] examples.+  - The //aperture_creation_params// are then sent to the dosimetry app as calculation requests following [[dosimetry:userguide:thinknode|thinknode™ calculation request]] examples.
     - <code cpp>     - <code cpp>
-// Compute the aperture shape. Parameters are: aperture_creation_params, smoothWeightFactor, smoothSizeFactor +// Compute the aperture shape. Parameters are: aperture_creation_params, smoothSize, iter, beam_geometry 
-aperture aper = compute_smoothed_aperture(ap_params, 10., 2.1);+aperture aper = compute_smoothed_aperture(ap_params, 1., 5, geometry);
 </code> </code>
  
Line 72: Line 79:
 Using exposed Dosimetry App functions an existing dose image can be used as a target structure for aperture creation. The //compute_triangle_mesh_from_image// function can be used to create a target from a dose iamge at a specified iso-level. Using exposed Dosimetry App functions an existing dose image can be used as a target structure for aperture creation. The //compute_triangle_mesh_from_image// function can be used to create a target from a dose iamge at a specified iso-level.
  
-Specific details of each function, argument parameters, and return values are provided at the [[http://docs.dosimetry.dotdecimal.com|Dosimetry App Manifest Guide]].+Specific details of each function, argument parameters, and return values are provided at the [[http://docs.apps.dotdecimal.com|Dosimetry App Manifest Guide]].
  
   *<code cpp>   *<code cpp>
Line 87: Line 94:
  
 <WRAP center 75%> <WRAP center 75%>
-<imgcaption ap_point_source| Point (single) source>{{:userguide:design_task_functions:aperture_point_source.png?nolink&250|}}</imgcaption> +<imgcaption ap_point_source| Point (single) source>{{dosimetry::userguide:design_task_functions:aperture_point_source.png?nolink&250|}}</imgcaption> 
-<imgcaption ap_dual_source| Dual source>{{:userguide:design_task_functions:aperture_dual_source.png?nolink&250|}}</imgcaption> +<imgcaption ap_dual_source| Dual source>{{dosimetry::userguide:design_task_functions:aperture_dual_source.png?nolink&250|}}</imgcaption> 
 </WRAP> </WRAP>
  
Line 122: Line 129:
 Enforcing machinability of the apertures at all evaluation steps is required in order to achieve plan vs. actual. Determining the machinable aperture shape is accomplished by performing an offset of the current “unmachinable” aperture shape by the radius of the final milling tool (in either the inward or outward direction) and then re-offsetting this result by the same distance. Machinability is enforced during aperture computation by using the //mill_radius// parameter of the //aperture_creation_params//.  Enforcing machinability of the apertures at all evaluation steps is required in order to achieve plan vs. actual. Determining the machinable aperture shape is accomplished by performing an offset of the current “unmachinable” aperture shape by the radius of the final milling tool (in either the inward or outward direction) and then re-offsetting this result by the same distance. Machinability is enforced during aperture computation by using the //mill_radius// parameter of the //aperture_creation_params//. 
  
-Additionally, smoothing can also be explicitly used to further simplify the aperture shape. +Additionally, smoothing can also be explicitly used to further simplify the aperture shape. As shown in <imgref ap_smoothalgorithm> below, a line segment (Line1) is created using the center points of the two edges that touch the vertex. A second line segment (Line2) is created going from the vertex to the center point of Line1. The vertex will be shifted along Line2 according the the //smoothSize// parameter of the //compute_smoothed_aperture// function. The value of //smoothSize// should be set between 0.0 and 1.0, indicating how far along Line2 the vertex will shift (0.5 will shift it to the center of Line2, and 1.0 will shift it to the intersection of Line1 and Line2). The //iter// parameter will indicate how many times the smoothing algorithm will act on the given aperture, with higher values resulting in more smoothing.
  
 The images below provide an exaggerated visual explanation of the creation options for aperture smoothing and mill radius.  The images below provide an exaggerated visual explanation of the creation options for aperture smoothing and mill radius. 
   - <imgref ap_beam_setup>: shows the beam setup of the example aperture   - <imgref ap_beam_setup>: shows the beam setup of the example aperture
 +  - <imgref ap_smoothalgorithm>: shows an example diagram of the smoothing algorithm. 
   - <imgref ap_noradiusnosmooth>: shows a resulting aperture shape with no mill radius and no smoothing applied to the aperture creation parameters    - <imgref ap_noradiusnosmooth>: shows a resulting aperture shape with no mill radius and no smoothing applied to the aperture creation parameters 
-    * Note: the dosimetry app api functions limit the mill radius if not specified to 4.7625mm (0.1875") or to be no smaller than 1.5875mm (0.0625")+    * Note: Recommended mill radius value is is 2.3815mm (0.09375") and advised to be no less than 0.79375mm (0.03125") to allow for accurate machining.
   - <imgref ap_radiusnosmooth>: shows a resulting aperture shape (black) with a large mill radius applied but not utilizing smoothing options in the compute aperture process.   - <imgref ap_radiusnosmooth>: shows a resulting aperture shape (black) with a large mill radius applied but not utilizing smoothing options in the compute aperture process.
-  - <imgref ap_radiussmooth>: shows a resulting aperture shape with a large mill radius applied to the aperture creation parameters and smoothing options using the //compute_smooth_aperture// function.+  - <imgref ap_radiussmooth>: shows a resulting aperture shape with a large mill radius applied to the aperture creation parameters and smoothing options using the //compute_smoothed_aperture// function.
  
-<imgcaption ap_beam_setup|Source (Red), Beam (Green), Aperture Plane (Gold), and Target (Blue)>{{ :userguide:design_task_functions:aperture_beam_setup.png?nolink&450 |}}</imgcaption> 
  
-<WRAP center 85%> +<WRAP center 50%> 
-<imgcaption ap_noradiusnosmooth|Aperture no mill radius or smoothing>{{:userguide:design_task_functions:aperture_no_smooth_radius.png?nolink&250|}}</imgcaption> +<imgcaption ap_beam_setup|Source (Red), Beam (Green), Aperture Plane (Gold), and Target (Blue)>{{ dosimetry:userguide:design_task_functions:aperture_beam_setup.png?nolink&450 |}}</imgcaption> 
-<imgcaption ap_radiusnosmooth|Aperture with a mill radius, no smoothing>{{:userguide:design_task_functions:aperture_no_smoothing.png?nolink&250|}}</imgcaption> +<imgcaption ap_smoothalgorithm|Method of smoothing>{{dosimetry:userguide:design_task_functions:new_smoothing.png?nolink&500|}}</imgcaption>
-<imgcaption ap_radiussmooth|Aperture with mill radius and smoothing>{{:userguide:design_task_functions:aperture_smoothing_radius.png?nolink&250|}}</imgcaption>+
 </WRAP> </WRAP>
  
 +<WRAP center 85%>
 +<imgcaption ap_noradiusnosmooth|Aperture no mill radius or smoothing>{{dosimetry:userguide:design_task_functions:aperture_original.png?nolink&250|}}</imgcaption>
 +<imgcaption ap_radiusnosmooth|Aperture with a mill radius, no smoothing>{{dosimetry:userguide:design_task_functions:aperture_mill_radius.png?nolink&250|}}</imgcaption>
 +<imgcaption ap_radiussmooth|Aperture with mill radius and smoothing>{{dosimetry:userguide:design_task_functions:aperture_smooth.png?nolink&250|}}</imgcaption>
 +</WRAP>
 ==== Aperture Shape Manipulation ==== ==== Aperture Shape Manipulation ====
  
Line 148: Line 159:
   * aperture_manual_override   * aperture_manual_override
  
-Below is a brief explanation of each of the manipulation tools and their intended effect (Specific details of each argument parameter are provided at the [[http://docs.dosimetry.dotdecimal.com|Dosimetry App Manifest Guide]]).+Below is a brief explanation of each of the manipulation tools and their intended effect (Specific details of each argument parameter are provided at the [[http://docs.apps.dotdecimal.com|Dosimetry App Manifest Guide]]).
  
 ** Example usage:** ** Example usage:**
Line 158: Line 169:
 ap_params.overrides.push_back(aperture_manual_override(make_polyset(poly), true)); ap_params.overrides.push_back(aperture_manual_override(make_polyset(poly), true));
 ap_params.half_planes.push_back(aperture_half_plane(make_vector(0., 0.), 45.)); ap_params.half_planes.push_back(aperture_half_plane(make_vector(0., 0.), 45.));
-aperture aper = compute_smoothed_aperture(ap_params, 10., 2.1);+aperture aper = compute_smoothed_aperture(ap_params, 1., 5, geometry);
 </code> </code>
 === Structure Centerline === === Structure Centerline ===
Line 166: Line 177:
 The aperture centerline defines a geometry using the centerline of a structure and a fixed width margin to create a region to remove from the aperture opening. In <imgref ap_centline_setup> the original aperture shape (blue), structure projection (orange), structure centerline projection (dotted red), and margin (dashed red) are shown. The resulting shape is the combination of the structure_centerline and the original aperture opening shape. The resulting final aperture shape is down in dashed black. The aperture centerline defines a geometry using the centerline of a structure and a fixed width margin to create a region to remove from the aperture opening. In <imgref ap_centline_setup> the original aperture shape (blue), structure projection (orange), structure centerline projection (dotted red), and margin (dashed red) are shown. The resulting shape is the combination of the structure_centerline and the original aperture opening shape. The resulting final aperture shape is down in dashed black.
  
-<imgcaption ap_centline_setup|>{{ :userguide:design_task_functions:aperture_centerline.png?nolink&450 |}}</imgcaption>+<imgcaption ap_centline_setup|>{{ dosimetry:userguide:design_task_functions:aperture_centerline.png?nolink&450 |}}</imgcaption>
  
 === Aperture Organ === === Aperture Organ ===
Line 176: Line 187:
 In <imgref ap_organ_setup> the original aperture shape (blue) and organ structure (red) are shown. With //occlude organ by target// set to false, the organ outline is projected to the aperture plane to limit the aperture opening shape. By setting the //occlude organ by target// to true, the target limits the organ projection to the aperture downstream edge plane, thus the organ projection has no effect on the aperture opening shape. The resulting final aperture shape is down in dashed black. In <imgref ap_organ_setup> the original aperture shape (blue) and organ structure (red) are shown. With //occlude organ by target// set to false, the organ outline is projected to the aperture plane to limit the aperture opening shape. By setting the //occlude organ by target// to true, the target limits the organ projection to the aperture downstream edge plane, thus the organ projection has no effect on the aperture opening shape. The resulting final aperture shape is down in dashed black.
  
-<imgcaption ap_organ_setup|>{{ :userguide:design_task_functions:aperture_occlude1.png?nolink&450 |}}</imgcaption>+<imgcaption ap_organ_setup|>{{ dosimetry:userguide:design_task_functions:aperture_occlude1.png?nolink&450 |}}</imgcaption>
  
 In <imgref ap_organ_setup1> the original aperture shape (blue) and organ structure (red) are shown. Because the organ is in front of the target (in BEV) the organ shape will always be projected to the aperture downstream edge plan and limit the aperture opening. The resulting final aperture shape is down in dashed black. In <imgref ap_organ_setup1> the original aperture shape (blue) and organ structure (red) are shown. Because the organ is in front of the target (in BEV) the organ shape will always be projected to the aperture downstream edge plan and limit the aperture opening. The resulting final aperture shape is down in dashed black.
  
-<imgcaption ap_organ_setup1|>{{ :userguide:design_task_functions:aperture_occlude.png?nolink&450 |}}</imgcaption>+<imgcaption ap_organ_setup1|>{{ dosimetry:userguide:design_task_functions:aperture_occlude.png?nolink&450 |}}</imgcaption>
  
 === Manual Override === === Manual Override ===
Line 188: Line 199:
 Manual override allows the manipulation of the aperture opening using a constructed polyset shape. Coordinates of the points making up the polygon at to be specified in BEV at the plane of the aperture downstream edge. The aperture opening can either be expanded to or limited based on the specified shape of the override polygons. <imgref manual_override> shows the aperture opening (black) and the override polygon (red). The override polygon can expand or limit the shape of the aperture opening based on the flags passed into the //aperture_creation_param//.  Manual override allows the manipulation of the aperture opening using a constructed polyset shape. Coordinates of the points making up the polygon at to be specified in BEV at the plane of the aperture downstream edge. The aperture opening can either be expanded to or limited based on the specified shape of the override polygons. <imgref manual_override> shows the aperture opening (black) and the override polygon (red). The override polygon can expand or limit the shape of the aperture opening based on the flags passed into the //aperture_creation_param//. 
  
-<imgcaption manual_override|Manual Override Shape>{{ :userguide:design_task_functions:aperture_manualoverrides.png?nolink&450 |}}</imgcaption>+<imgcaption manual_override|Manual Override Shape>{{ dosimetry:userguide:design_task_functions:aperture_manualoverrides.png?nolink&450 |}}</imgcaption>
  
  
Line 197: Line 208:
 The aperture half and corner planes define a geometry that can be used to remove the portion of the aperture opening in the region on the positive sides (side to which the normal points) of the planes. This feature is necessary in order to create match field aperture devices. In <imgref ap_planes>, the first plane is defined by the origin (0., 0.) and a normal direction of 0 degrees (along the positive x axis). The second plane is defined by the same point, and a normal direction of 90 degrees (along the positive y axis). The result (black) shows how the aperture opening is clipped by removing from the shape anything that is on the positive side of **both** planes. This same principle can be used with the //aperture_half_plane// parameter, but instead only specifying one plane to clip the aperture by. The aperture half and corner planes define a geometry that can be used to remove the portion of the aperture opening in the region on the positive sides (side to which the normal points) of the planes. This feature is necessary in order to create match field aperture devices. In <imgref ap_planes>, the first plane is defined by the origin (0., 0.) and a normal direction of 0 degrees (along the positive x axis). The second plane is defined by the same point, and a normal direction of 90 degrees (along the positive y axis). The result (black) shows how the aperture opening is clipped by removing from the shape anything that is on the positive side of **both** planes. This same principle can be used with the //aperture_half_plane// parameter, but instead only specifying one plane to clip the aperture by.
  
-<imgcaption ap_planes|Aperture Corner Planes>{{ :userguide:design_task_functions:aperture_planes.png?nolink&450 |}}</imgcaption>+<imgcaption ap_planes|Aperture Corner Planes>{{ dosimetry:userguide:design_task_functions:aperture_planes.png?nolink&450 |}}</imgcaption>
  
 ===== Range Compensator Design ===== ===== Range Compensator Design =====
  
-The following example assumes you are familiar with the [[http://docs.dosimetry.dotdecimal.com|dosimetry functions and types]]. These examples will provide a rough process of creating a proton range compensator surface in C++ using pre-existing libraries. The code here is meant to be used as a guide on the process to follow and functions/data types to construct.+The following example assumes you are familiar with the [[http://docs.apps.dotdecimal.com|dosimetry functions and types]]. These examples will provide a rough process of creating a proton range compensator surface in C++ using pre-existing libraries. The code here is meant to be used as a guide on the process to follow and functions/data types to construct.
  
   * **compute_optimized_rc:**   * **compute_optimized_rc:**
Line 256: Line 267:
 The <imgref rc_patch_setup> example below shows a brief explanation of the usage: The <imgref rc_patch_setup> example below shows a brief explanation of the usage:
  
-<imgcaption rc_patch_setup|Range Compensator Patch Field>{{ :userguide:design_task_functions:rangecomp_patch.png?nolink&450 |}}</imgcaption>+<imgcaption rc_patch_setup|Range Compensator Patch Field>{{ dosimetry:userguide:design_task_functions:rangecomp_patch.png?nolink&450 |}}</imgcaption>
  
 The target (green) is shown within the 3D image (blue & red) that represents the current dose of the target that has been delivered from another field angle. The blue values of the image represent zero dose while the red 100%. Passing this //current_dose// image and a //patch_distal_dose// of 20 to the //rc_opt_properties// will limit the range compensator distal surface to the target distal surface while taking consideration of the 20% isodose line of the current dose. The target (green) is shown within the 3D image (blue & red) that represents the current dose of the target that has been delivered from another field angle. The blue values of the image represent zero dose while the red 100%. Passing this //current_dose// image and a //patch_distal_dose// of 20 to the //rc_opt_properties// will limit the range compensator distal surface to the target distal surface while taking consideration of the 20% isodose line of the current dose.
Line 262: Line 273:
 An approximation of the resulting range compensator surface is shown in <imgref rc_patch_surface> below. An approximation of the resulting range compensator surface is shown in <imgref rc_patch_surface> below.
  
-<imgcaption rc_patch_surface|Resulting Range Compensator w/ Patch Dose>{{ :userguide:design_task_functions:rangecomp_patch_surface.png?nolink&450 |}}</imgcaption>+<imgcaption rc_patch_surface|Resulting Range Compensator w/ Patch Dose>{{ dosimetry:userguide:design_task_functions:rangecomp_patch_surface.png?nolink&450 |}}</imgcaption>
  
 ---- ----
dosimetry/userguide/design_task_functions/dtf.1435852076.txt.gz · Last modified: 2021/07/29 18:24 (external edit)