decimal App Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Planning App User Guide ======

===== Overview =====

The .decimal Astroid Planning App is used for treatment planning of proton radiation therapy treatments. The Astroid Planning App is an interactive end user application that leverages the existing .decimal Dosimetry App functions for device creation, dose calculation, and optimization to facilitate efficient development of proton radiation treatment plans.

===== Purpose =====

The purpose of this document is to provide guidance on the setup, access, and usage of the Astroid Planning App. 

===== Getting Started =====

Proper use of this software is critical to safe and effective treatment of patients using plans generated by this application. Users are expected to read and understand this complete User Guide including the [[planning:instructions_for_use:instructions_for_use|Instructions for Use]], which outlines the general usage principles and limitations of the Astroid Planning App. Users must read and understand these instructions before operating the system for clinical use. Refer to each section below for complete details:
  * **[[planning:instructions_for_use:instructions_for_use|Instructions for Use]]**
    * [[planning:instructions_for_use:instructions_for_use#overview_and_indications_for_use|Overview and Indications for Use]]
    * [[planning:instructions_for_use:instructions_for_use#user_responsibilities|User Responsibilities]]
    * [[planning:instructions_for_use:instructions_for_use#warning|Warning]]
    * [[planning:instructions_for_use:instructions_for_use#intended_use|Intended Use]]
    * [[planning:instructions_for_use:instructions_for_use#user_profile|User Profile]]
    * [[planning:instructions_for_use:instructions_for_use#product_features|Product Features]]
    * [[planning:instructions_for_use:instructions_for_use#Data Model|Data Model]]


==== Precautions ====

It is the responsibility of those utilizing this application to ensure all that all usages of this product relating to patient treatments are performed by trained and qualified personnel only and that such personnel is aware that the quality of any generated treatment plans is highly dependent on the quality and correctness of the input data; therefore if any questions or uncertainties exist regarding the quality, units, or identification of input data arise, they must be investigated and resolved before the data are used.

==== Initial Setup ====

Once Astroid has been purchased, Astroid staff will assist with beam model creation, software installation, and user training. Users will be generally be trained at two separate levels, system administrators and end users. System administrators will be setup with appropriate access and tools for managing software including both the local and cloud resources. End users will be primarily trained on the details of generating high-quality treatment plans using the local client portion of the application suite. The beam modeling and equipment setup processes are explained more fully in the [[http://apps.dotdecimal.com/doku.php?id=dosimetry:commissioning_guide:commissioning_guide|Dosimetry App Commissioning Guide]].

=== Installation ===

The Astroid Planning App includes both a local User Client and a cloud-based calculation provider, therefore, there are specific requirements on computers in which the local client application can be installed. Please see the [[planning:userguide:systemrequirements|System Requirements]] page for details.

=== Site Settings and Defaults ===

The astroid Planning App provides a RKS record for specifying site level configurations and defaults. The RKS entry exists at the root level of the realm for which the app is installed. The record holds a site_info, whose definition can be viewed at the [[http://docs.apps.dotdecimal.com/|astroid Manifest Documentation site]]. An empty {{ :planning:userguide:sample_site_info.json | sample json version}} of the site_info is provided.

To update the site_info RKS record, perform the following steps. Note: you must have Thinknode //"iam:buckets:unlockEntries"// policy permissions in order to unlock this RKS record to update it.
  - Using the Thinknode Client or manual [[https://developers.thinknode.com/services/rks/entries| RKS GET]] routes view the RKS records for the realm in which you wish to update the site_info
  - Find, or create if it's missing, the RKS record named "site_info" at the root level of the RKS entries
  - Unlock the site_info RKS record using the Thinknode [[https://developers.thinknode.com/services/rks/entries| PUT /rks/:id/unlock]] route
  - Edit the site_info by either:
    - Editing in place the site_info data using the Thinknode Client or
    - Post new site_info data as an immutable object and update the Reference ID for the RKS entry
  - Lock the site_info RKS record using the Thinknode [[https://developers.thinknode.com/services/rks/entries| PUT /rks/:id/lock]] route to prevent unrestricted changes.

=== Site Facility Model ===

The [[planning:userguide:userguide#site_settings_and_defaults|site_info]] for the astroid Planning App references the [[http://apps.dotdecimal.com/doku.php?id=dosimetry:commissioning_guide:commissioning_guide#data_requirements|astroid Dosimetry App machine model]]. This model must be posted and referenced from within the site_info rks record.



==== Keyboard and Mouse Controls ====

Astroid utilizes keyboard shortcuts to help streamline many commonly used functions and display controls. A complete listing of these shortcuts along with a full description of the mouse controls is located at the [[planning:userguide:userguide:keyboard_controls| Keyboard and Mouse Controls page]].
===== Tutorials =====

==== Task Descriptions ====

The following task descriptions are thorough guides providing complete information about each task within the Astroid Planning Application.

  * [[planning:userguide:tutorials:all_tutorials#launching_astroid|Launching the Astroid Planning App]]
  * [[planning:userguide:tutorials:all_tutorials#uploading_dicom_patient_files|Uploading DICOM Patient Files]]
  * [[planning:userguide:tutorials:all_tutorials#importing_patient_data|Importing Patient Data]]
  * [[planning:userguide:tutorials:all_tutorials#courses|Courses, Intents, and Directives]] 
  * [[planning:userguide:tutorials:all_tutorials#patient_models|Patient Models]]
  * [[planning:userguide:tutorials:all_tutorials#creating_a_plan|Creating a Plan]]
    * [[planning:userguide:tutorials:all_tutorials#structures|Structures]]
    * [[planning:userguide:tutorials:all_tutorials#dose_grid|Dose Grid]]
    * [[planning:userguide:tutorials:all_tutorials#proton_beams|Proton Beams]]
      * [[planning:userguide:tutorials:all_tutorials#creating_an_aperture|Defining an Aperture]]
      * [[planning:userguide:tutorials:all_tutorials#creating_a_range_compensator|Defining a Range Compensator]]
    * [[planning:userguide:tutorials:all_tutorials#astroid_optimization_pbs|Astroid Optimization]] (PBS)
      * [[planning:userguide:tutorials:all_tutorials#pbs_fraction_groups|PBS Fraction Groups]]
      * [[planning:userguide:tutorials:all_tutorials#optimization_constraints|Defining Constraints]]
      * [[planning:userguide:tutorials:all_tutorials#feasibility_and_constraints|Feasibility & Constraints]]
      * [[planning:userguide:tutorials:all_tutorials##optimization_objectives|Setting Objectives]]
      * [[planning:userguide:tutorials:all_tutorials#running_the_optimizer|Running the Optimizer]]
      * [[planning:userguide:tutorials:all_tutorials#dose_normalization_and_display|Dose Normalization]]
      * [[planning:userguide:tutorials:all_tutorials#navigating_the_solutions|Navigating the Solutions]]
    * [[planning:userguide:tutorials:all_tutorials#beam_delivery_sobp|Beam Delivery]] (SOBP)
      * [[planning:userguide:tutorials:all_tutorials#sobp_fraction_groups|SOBP Fraction Groups]]
    * [[planning:userguide:tutorials:all_tutorials#plan_history|Using the Plan History]]
    * [[planning:userguide:tutorials:all_tutorials#plan_publishing|Publishing a Plan]]
  * [[planning:userguide:tutorials:all_tutorials#plan_templates|Plan Templates]]
  * [[planning:userguide:tutorials:all_tutorials#plan_export|Exporting a Plan]]

/*
    
    * [[planning:userguide:tutorials:all_tutorials#plan_reports|Generating Plan Reports]] 
*/
  * More coming soon ...


==== End-to-End (Plan) Walkthroughs ====

The following walkthroughs will take you through the process of creating complete treatment plans in the Astroid Planning App. They provide detailed steps so that any user can begin using the software. Each guide covers a specific type of treatment plan, and although some walkthroughs share certain steps, each has been written as a self-contained unit so that you may begin with whatever guide is the most useful.

  * [[planning:userguide:walkthroughs:all_walkthroughs#prostate_plan_walkthrough|Prostate Plan Walkthrough]]

/* * [[planning:userguide:walkthroughs:all_walkthroughs#complex_plan_walkthrough|Head and Neck Plan Walkthrough]] */
===== System Usage ===== 

==== Improper System Usage ====

When using the Astroid Planning App, as with any complex program, there is the potential for misuse. The various Astroid Apps comprise a suite of radiotherapy treatment planning tools that are intended to be used by experienced and knowledgeable professionals working in the field of radiation therapy.

===== Known Application Limitations =====

Below are listed the known application limitations, defects, or inconsistencies.

=== General ===

  - Astroid uses DICOM patient space coordinates for all slice and 3D views and IEC 61217 coordinate systems for BEV (other options, such as machine based coordinate systems are NOT available at this time)
  - If a user's computer is abruptly shut down (e.g. computer crash or power failure) while the Astroid Planning App has a plan open, there is a potential for the user's local data cache index file to become corrupted. If this happens, generally the Planning App will automatically close (crash) whenever the user tries to open the plan that was active at the time of crash. In order to fix this, the user must close the Planning App and delete the entire cache folder. The default directory location for this folder should be C:\Users\All Users\Astroid2\cache. If the location has been changed, the new location can be found within the Planning App from the //View-->Settings// menu.
  - If a user starts a calculation using the calculation status UI (e.g.: feasibility or MCO) and is outside the block the interface is in when the calculation finishes, the status of the calculation will remain "calculating". Manually refreshing data (pressing F5) or re-launching the application resolves this issue.
    * This issue may also apply to other requests and calculations in the application too
  - Treatment plans store an optional fluence override vector which will be used instead of the optimization fluence results if present. These overrides must be added via scripts outside the Planning App UI. If an override is present in a plan the Planning App UI becomes mostly read-only to limit the potential for changes that could invalidate the fluence override. However there are no hard stops to ensure that the fluence override vectors are properly sized for the plan at hand, so users must ensure properly sized fluence vectors are set in their scripts.

=== DICOM Upload ===
  - The Uploads block must remain open while uploading DICOM files.

=== DICOM Export ===
  - Computed treatment plan dose is required prior to users being able to export DICOM files.
    * Note: Users may still be able to attempt to export DICOM files from the user interface, but may encounter errors if their plan does not have, or is unable to, compute dose.
  - DICOM Export of CT and SS files searches the RKS for the CT image record, therefore modifying the RKS record of the CT images can cause changes to the exported data even on an approved plan (deleting the record will prevent export of CT and SS altogether)

=== Importing ===

  - When importing a new patient, the default physician will be set from the DICOM file. When this physician selection is changed, either during import or later in the Patient Overview, there is no way to re-select the original from DICOM physician.

=== Plan Templates ===

  - Plan templates are unable to be edited and/or removed from within the Planning App without manually manipulating the RKS record.
  - All referenced and used structures in the original plan template must exist in the new patient model for which the plan template is being used.

=== Structures ===

  - When changing a structure type from a TARGET, whether at the Patient Model or Plan level, if that structure was an existing optimization constraint or objective with maximize options selected, those options will continue to be selected and will unable to be changed in the UI. They can be viewed in the optimization constraint and objective summaries, but will not be editable unless the structure type is changed back to TARGET.
    - This can result in you having constraints or objectives that might not be ideal for this type of structure. Always double check the constraint/objective summaries if you need to change a structure type from TARGET after you've added optimization parameters to that structure.
  - Structures that are expanded in the axis of the CT image slices will have the expansion distance limited by the CT image spacing. So the expansion distance may appear to be an incorrect distance. 
  - When creating a new target for a PBS beam via the Create subtask from the Geometric Target drop down, you are able to create a non target structure and have it be selected in this drop down. This is only possible when the Create subtask automatically populates the dropdown upon finishing, and you will not be able to select this target manually if you change the selection.

=== Facility Model ===

  - When multiple machines are defined in the facility model each room must have a unique name within the entire facility model. The treatment_plan references a treatment_room by it's name and assumes this name will only exist one time in the facility model.

=== Machine/Patient Collision ===

  - Astroid does not detect possible collisions between the patient and snout or the treatment table and snout. It is the users responsibility to ensure that there is enough distance between the patient/table and the snout so as to avoid collisions.

=== SOBP Patch Fields ===

  - For SOBP plans with patch fields, dose overlap at the patch junction may result in a maximum dose that exceeds the limits of the isobands and DHV displays
  - If a patch field is added to an existing thru-beam that's already in a fraction group, the thru-beam must be removed and re-added to the fraction group for the patch field to be included in the fraction group's beam list.


See [[planning:userguide:errors|Thinknode Errors]] for common problems that can occur during usage of the Planning app.

Should you discover or suspect any additional errors or limitations not noted above, please alert the .decimal Astroid Planning App development team by providing creating a ticket at dotdecimal.freshdesk.com including details of your concerns and steps to reproduce the issue. All concerns will be addressed as quickly as possible and follow up with the submitter will occur throughout the inquiry and correction process.


===== ResultsAPI =====

{{page>planning:userguide:results_api#Planning App ResultsAPI&noheader&firstseconly&noreadmore&nofooter}}


Please refer to the [[planning:userguide:results_api|Planning App ResultsAPI Guide]] for a more detailed look at explanation, usages, and examples of the Planning App ResultsAPI.


----

<WRAP center 60%>.decimal LLC, 121 Central Park Place Sanford, FL. 32771 1-800-255-1613</WRAP>