Pinnacle Export Tool

Summary

A tool to export DICOM objects from raw Pinnacle data:

>>> from pymedphys.labs.pinnacle import (
...     PinnacleExport,
...     PinnaclePlan,
...     PinnacleImage)

Warning

The DICOM objects exported by this tool are not the same as the DICOM objects exported from within the Pinnacle application. Certain DICOM modalities correspond fairly well to the Pinnacle exported objects for some versions of Pinnacle. Others are not working as expected or have not been validated.

The first step when using this tool is to compare the output generated to the ‘ground truth’ generated by your version(s) of Pinnacle. You can then determine if this tool currently meets your export needs, or if some adjustments need to be made. Please create an issue on the PyMedPhys GitHub describing the circumstances where the tool is not working, providing some sample raw Pinnacle data where possible. If you’re up for a challenge, clone the PyMedPhys repository and attempt to solve the problem yourself! Don’t be afraid to ask for help when contributing your changes. The more developers we can encourage to contribute to this tool, the sooner it will become stable and reliable.

Finally, note that while this tool can be extremely useful for exporting large amounts of Pinnacle data to DICOM, we recommend that this should only be used for research purposes and not clinically.

API

class pymedphys.labs.pinnacle.PinnacleExport(path, logger=None)[source]

Handle Pinnacle data to allow export of DICOM objects

This class is used to export the various DICOM objects from Pinnacle data found within the given path.

Parameters:
  • path (str) – Path to raw Pinnacle data (directory containing ‘Patient’ file).
  • logger (Logger) – Logger the tool will log to.
export_dose(plan, export_path='.')[source]

Exports the RTDOSE DICOM modality.

Parameters:
  • plan (PinnaclePlan) – The plan for which dose should be exported.
  • export_path (str, optional) – The file system path where the DICOM object should be exported to.
export_image(image=None, series_uid='', export_path='.')[source]

Exports an image from the Pinnacle data.

Parameters:
  • image (PinnacleImage, optional) – The image to export.
  • series_uid (str, optional) – The SeriesInstanceUID of the image to export.
  • export_path (str, optional) – The file system path where the DICOM objects should be exported to.
export_plan(plan, export_path='.')[source]

Exports the RTPLAN DICOM modality.

Parameters:
  • plan (PinnaclePlan) – The plan for which dose should be exported.
  • export_path (str, optional) – The file system path where the DICOM object should be exported to.
export_struct(plan, export_path='.')[source]

Exports the RTSTRUCT DICOM modality.

Parameters:
  • plan (PinnaclePlan) – The plan for which structures should be exported.
  • export_path (str, optional) – The file system path where the DICOM object should be exported to.
images

Get the images available.

Returns:images – List of PinnacleImage’s available within the Pinnacle raw data in the path configured.
Return type:list
log_images()[source]

Outputs all images found in the Pinnacle data to the log.

log_plan_names()[source]

Outputs all plans found in the Pinnacle data to the log.

log_trial_names()[source]

Outputs all trials found in the Pinnacle data to the log.

log_trial_names_in_plan(plan)[source]

Outputs all trials found within a plan to the log.

Parameters:plan (PinnaclePlan) – The plan for which to log the trials.
logger

Gets the configured logger.

Returns:logger – Logger configured.
Return type:Logger
patient_info

Gets the patient info.

Returns:patient_info – Dictionary object containing the data found in the ‘Patient’ file within the raw Pinnacle data.
Return type:dict
plans

Get the plans available.

Returns:plans – List of PinnaclePlan’s available within the Pinnacle raw data in the path configured.
Return type:list
class pymedphys.labs.pinnacle.PinnaclePlan(pinnacle, path, plan)[source]

Represents a plan within the Pinnacle data.

This class manages the data specific to a plan within a Pinnacle dataset.

Parameters:
  • pinnacle (PinnacleExport) – PinnacleExport object representing the dataset.
  • path (str) – Path to raw Pinnacle data (directoy containing ‘Patient’ file).
  • plan (dict) – Plan info dict from ‘Patient’ file.
active_trial

Get and set the active trial for this plan.

When DICOM objects are exported, data from the active trial is used to generate the output.

convert_point(point)[source]

Convert a point from Pinnacle coordinates to DICOM coordinates.

Parameters:point (list) – The point to convert.
Returns:
Return type:The converted point.
dose_inst_uid

Gets the instance UID for RTDOSE.

Returns:uid – The UID to use for the dose.
Return type:str
generate_uids(uid_type='HASH')[source]

Generates UIDs to be used for exporting this plan.

Parameters:uid_type (str, optional) – If ‘HASH’, the entropy will be generated to hash to consistant UIDs. If not then random UIDs will be generated. Default: ‘HASH’
is_prefix_valid(prefix)[source]

Check if a UID prefix is valid.

Parameters:prefix (str) – The UID prefix to check.
Returns:
True if valid, False otherwise.
iso_center

Gets and sets the iso center for this plan.

logger

Gets the configured logger.

Returns:logger – Logger configured.
Return type:Logger
machine_info

Gets the machine info for this plan.

Returns:machine_info – Machine info read from ‘plan.Pinnacle.Machines’ file.
Return type:dict
path

Gets the path of the Pinnacle data.

Returns:path – Path containing the Pinnacle data.
Return type:str
patient_position

Gets the patient position

Returns:patient_position – The patient position for this plan.
Return type:str
pinnacle

Gets the PinnacleExport object.

Returns:pinnacle – PinnacleExport object for this dataset.
Return type:PinnacleExport
plan_info

Gets the plan information for this plan.

Returns:plan_info – Plan info as found in the Pinnacle ‘Patient’ file.
Return type:dict
plan_inst_uid

Gets the instance UID for RTPLAN.

Returns:uid – The UID to use for the plan.
Return type:str
points

Gets the points defined within the plan.

Returns:points – List of points read from the ‘plan.Points’ file.
Return type:list
primary_image

Gets the primary image for this plan.

Returns:primary_image – PinnacleImage representing the primary image for this plan.
Return type:PinnacleImage
struct_inst_uid

Gets the instance UID for RTSTRUCT.

Returns:uid – The UID to use for the struct.
Return type:str
trial_info

Gets the trial information of the active trial.

Returns:trial_info – Trial info from the ‘plan.Trial’ file.
Return type:dict
trials

Gets the trials within this plan.

Returns:trials – List of all trials found within this plan.
Return type:list
class pymedphys.labs.pinnacle.PinnacleImage(pinnacle, path, image)[source]

Represents an image within the Pinnacle data.

This class manages the data specific to an image within a Pinnacle dataset.

Parameters:
  • pinnacle (PinnacleExport) – PinnacleExport object representing the dataset.
  • path (str) – Path to raw Pinnacle data (directoy containing ‘Patient’ file).
  • image (dict) – Image info dict from ‘Patient’ file.
image

Gets the image information from the ‘Patient’ file.

Returns:image – Image info as found in the Pinnacle ‘Patient’ file.
Return type:dict
image_header

Gets the image header from the ‘.header’ file.

Returns:image_header – Image info as found in the Pinnacle ‘.header’ file.
Return type:dict
image_info

Gets the image information from the ‘.ImageInfo’ file.

Returns:image_info – Image info as found in the Pinnacle ‘.ImageInfo’ file.
Return type:dict
image_set

Gets the image set from the ‘.ImageSet’ file.

Returns:image_set – Image set as found in the Pinnacle ‘.ImageSet’ file.
Return type:dict
logger

Gets the configured logger.

Returns:logger – Logger configured.
Return type:Logger
path

Gets the path of the Pinnacle data.

Returns:path – Path containing the Pinnacle data.
Return type:str
pinnacle

Gets the PinnacleExport object.

Returns:pinnacle – PinnacleExport object for this dataset.
Return type:PinnacleExport