# DICOM-SEG-to-OHIF
## Overview
DICOM SEGs are segmentation files that include ROI segment information
and pixel data related to a source DICOM file. The dicom-seg-to-ohif gear
is provided so that these segments can be converted to OHIF annotations
compatible with the Flywheel viewer.
### Summary
This Flywheel gear converts DICOM SEG ROIs to OHIF annotations.
### Cite
No citations noted.
### License
*License:* *MIT*
### Classification
*Category:* *Converter*
*Gear Level:*
- [ ] Project
- [ ] Subject
- [ ] Session
- [X] Acquisition
- [ ] Analysis
----
[[_TOC_]]
----
### Inputs
- *dicom_seg*
- __Name__: *dicom_seg*
- __Type__: *DICOM file*
- __Optional__: *False*
- __Description__: *DICOM SEG file with one or more segments*
- *source_dicom*
- __Name__: *source_dicom*
- __Type__: *DICOM file*
- __Optional__: *True*
- __Description__: *Optional: Source DICOM connected to DICOM SEG*
- __Notes__: *A source DICOM file is required for the gear to run.*
*If not provided as input, the gear will search the session container*
*for a DICOM that corresponds with the inputted DICOM SEG. If a source*
*DICOM is not identified (or more than one is identified), the gear*
*will fail and log instructions to re-run the gear with source_dicom*
*explicitly inputted into the gear.*
### Config
- *debug*
- __Name__: *debug*
- __Type__: *boolean*
- __Description__: *Log debug messages*
- __Default__: *False*
- *task_id*
- __Name__: *task_id*
- __Type__: *string*
- __Description__: *Task ID of the task in which to store the created annotations.*
- __Optional__: *True*
- __Notes__: *Gear requires either task_id OR protocol_id. If neither are*
*provided, gear will exit and log an error requesting that the gear be*
*re-run with either a valid task_id or protocol_id provided.*
- *protocol_id*
- __Name__: *protocol_id*
- __Type__: *string*
- __Description__: *Protocol ID of the protocol to use when creating a*
*new task, if no task_id.*
- __Optional__: *True*
- __Notes__: *Gear requires either task_id OR protocol_id. If neither are*
*provided, gear will exit and log an error requesting that the gear be*
*re-run with either a valid task_id or protocol_id provided. If both a*
*task_id and protocol_id are inputted, gear will strictly*
*utilize the task_id.*
- *annotation_description*
- __Name__: *annotation_description*
- __Type__: *string*
- __Description__: *Additional information to be appended to each created annotation's `description` field.*
- __Optional__: *True*
- *if_annotations_exist*
- __Name__: *if_annotations_exist*
- __Type__: *string*
- __Description__: *Selected behavior if `task_id` is provided and other annotations*
*are already connected to the task. Options are `override`, `append`, `exit`.*
- __Default__: `exit`
- *assignee*
- __Name__: *assignee*
- __Type__: *string*
- __Description__: *If creating a new task, the Flywheel user the task is to be assigned.*
*If left blank, the assignee will default to the user running the gear. User ID is the*
*login email address, i.e "susannahtrevino@flywheel.io".*
- __Optional__: *True*
### Outputs
This gear outputs OHIF annotations attached to a task container, viewable
with the Flywheel Viewer. More information on tasks can be found
[here](https://docs.flywheel.io/User_Guides/user_introduction_to_read_tasks/).
Please note that this gear can only run on Flywheel instances where
read tasks are enabled. If you do not have read tasks enabled or are
unsure that your instance is set up for this, please contact your
Flywheel Representative.
#### Files
No files are outputted by this gear.
#### Metadata
No metadata is created or modified by this gear.
### Pre-requisites
#### Prerequisite Gear Runs
No prerequisite gear runs are required by this gear.
#### Prerequisite Files
No prerequisite files are required by this gear.
#### Prerequisite Metadata
Prerequisite metadata are not required by this gear.
## Usage
### Description
This gear takes as input a DICOM SEG with one or more segments. It
provides as output OHIF annotation representations of these segmentations.
These annotations are stored in a task container as specified by the
`task_id` or `protocol_id` config. If a task_id is specified, the
existing task will be utilized as the container for the annotations. If
protocol_id is specified, the gear will create a new task utilizing the
given protocol_id. The annotations are overlaid on the source DICOM.
#### File Specifications
This gear can be run on a DICOM SEG with one or more segmentations,
where the source DICOM is either found in the same session container
as the inputted DICOM SEG or inputted explicitly.
#### Known Limitations
This gear assumes that if Derivation Image Sequence and Source Image
Sequence DICOM tags exist, there is exactly one of each. This gear does
not currently handle cases where multiple of one or both tags are present
in the source DICOM.
Oblique images (not axial/sagittal/coronal) are not supported by this gear.
### Workflow
```mermaid
graph LR;
A[DICOM SEG]:::input --> E;
B[Source DICOM]:::input -.->|optional| E((DICOM-SEG-to-OHIF));
C[task_id or protocol_id] --> E;
E:::gear --> G[OHIF annotations \n attached to \n task container]:::container;
classDef container fill:#57d,color:#fff
classDef input fill:#7a9,color:#fff
classDef gear fill:#659,color:#fff
```
Description of workflow
1. Upload DICOM SEG to acquisition container
1. Upload source DICOM to acquisition container within the same
session as the DICOM SEG
1. Select DICOM SEG as input to gear
1. Gear attaches output OHIF annotations to task
### Use Cases
#### Use Case 1: DICOM SEG with gear-identified source DICOM
__*Conditions:*__
- DICOM SEG and source DICOM are uploaded to the same session container
- Exactly one DICOM within the session container matches the DICOM SEG
After inputting the DICOM SEG and beginning the gear run, the gear will
search for the source DICOM within the session container. The gear
will then utilize the source DICOM as needed in conjunction with the
DICOM SEG to create the OHIF annotation output.
#### Use Case 2: DICOM SEG with inputted source DICOM
__*Conditions:*__
- DICOM SEG and source DICOM are uploaded to Flywheel
- Source DICOM is not in the same session container, or multiple
DICOMs in the session container match the DICOM SEG
The DICOM SEG and source DICOM must both be provided as inputs. The
gear will utilize the inputted source DICOM instead of searching
for the file within the session container.
#### Use Case 3: Attaching OHIF annotations to already-existing task
__*Conditions:*__
- Task with which to contain the annotations is already created
By inputting the `task_id` of the already-created task, this gear will
connect all outputted annotations to the designated task.
#### Use Case 4: Comparing two sets of segmentations in OHIF
__*Conditions:*__
- Task with which to contain the annotations is already created
- Multiple DICOM-SEG files exist for the same source DICOM
- User wants to compare the two DICOM-SEG annotations
By running this gear twice with two different DICOM-SEG files and configuring
the gear run with the same `task_id` and setting `if_annotations_exist="append"`,
both gear runs will add annotations to the same task container. By configuring
`annotation_description` with contrasting text (i.e. information about how the
DICOM-SEG was created), these annotations can be better identified while
utilizing the Flywheel Viewer.
#### Use Case 5: Attaching OHIF annotations to new task with existing protocol
__*Conditions:*__
- New task is needed to contain the annotations
- Protocol with which to create a new task exists
By inputting the `protocol_id` of the protocol to be used to create a
new task, the gear will initialize a new task with the given protocol,
allowing protocol configurations to be re-used for each new task.
#### Use Case 6: Attaching OHIF annotations to new task, no existing protocol
__*Conditions:*__
- New task is needed to contain the annotations
- A protocol with which to create a new task does not yet exist
In Flywheel, all read tasks require a protocol. This protocol sets a variety
of configuration options, and without a protocol, any attached annotations
would not be viewable within the Flywheel Viewer.
One way to create a new protocol is via a python script. The below code
snippet can be used for this purpose, leveraging FWClient to make API calls:
```python
from fw_client import FWClient
fw = FWClient(api_key=api_key) # Insert your API key here
form_info = {
"viewer": "OHIF",
"parent": {
"type": container, # site/project
"id": parent_id # id of container
},
"form": {} # If desired, a form can be configured here; left blank will initialize the task without an attached form.
}
form = fw.post('/api/forms', json=form_info)
viewer_info = {
"name": "DICOM SEG viewer config", # Can be changed
"config": {} # If desired, viewer config options can be added here; left blank will initialize the default viewer.
}
viewer = fw.post('/api/viewerconfigs', json=viewer_info)
protocol_info = {
"label": "DICOM SEG to OHIF", # Can be changed
"description": "Protocol for DICOM SEG to OHIF", # Can be changed
"form_id": form._id,
"viewer_config_id": viewer._id,
"parent": {
"type": container, # Match the container provided for form_info
"id": parent_id # Match the parent_id provided for form_info
}
}
protocol = fw.post('/api/read_task_protocols', json=protocol_info)
print(protocol._id)
```
### Logging
This gear logs information about the gear run, including configuration settings,
segments found within the DICOM SEG, and calls made to the Flywheel API.
If the gear run encounters a known error, the gear logs what occurred and, if
applicable, what to do to fix the error in a subsequent run.
## FAQ
[FAQ.md](docs/faq.md)
## Contributing
For more information about how to get started contributing to that gear,
checkout [CONTRIBUTING.md](CONTRIBUTING.md).
<!-- markdownlint-disable-file -->
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/flywheel-io/scientific-solutions/gears/dicom-seg-to-ohif",
"name": "fw-gear-dicom-seg-to-ohif",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "Flywheel, Gears",
"author": "Flywheel",
"author_email": "support@flywheel.io",
"download_url": null,
"platform": null,
"description": "# DICOM-SEG-to-OHIF\n\n## Overview\n\nDICOM SEGs are segmentation files that include ROI segment information\nand pixel data related to a source DICOM file. The dicom-seg-to-ohif gear\nis provided so that these segments can be converted to OHIF annotations\ncompatible with the Flywheel viewer.\n\n### Summary\n\nThis Flywheel gear converts DICOM SEG ROIs to OHIF annotations.\n\n### Cite\n\nNo citations noted.\n\n### License \n\n*License:* *MIT*\n\n### Classification\n\n*Category:* *Converter*\n\n*Gear Level:*\n\n- [ ] Project\n- [ ] Subject\n- [ ] Session\n- [X] Acquisition\n- [ ] Analysis\n\n----\n\n[[_TOC_]]\n\n----\n\n### Inputs\n\n- *dicom_seg*\n - __Name__: *dicom_seg*\n - __Type__: *DICOM file*\n - __Optional__: *False*\n - __Description__: *DICOM SEG file with one or more segments*\n- *source_dicom*\n - __Name__: *source_dicom*\n - __Type__: *DICOM file*\n - __Optional__: *True*\n - __Description__: *Optional: Source DICOM connected to DICOM SEG*\n - __Notes__: *A source DICOM file is required for the gear to run.*\n *If not provided as input, the gear will search the session container*\n *for a DICOM that corresponds with the inputted DICOM SEG. If a source*\n *DICOM is not identified (or more than one is identified), the gear*\n *will fail and log instructions to re-run the gear with source_dicom*\n *explicitly inputted into the gear.*\n\n### Config\n\n- *debug*\n - __Name__: *debug*\n - __Type__: *boolean*\n - __Description__: *Log debug messages*\n - __Default__: *False*\n- *task_id*\n - __Name__: *task_id*\n - __Type__: *string*\n - __Description__: *Task ID of the task in which to store the created annotations.*\n - __Optional__: *True*\n - __Notes__: *Gear requires either task_id OR protocol_id. If neither are*\n *provided, gear will exit and log an error requesting that the gear be*\n *re-run with either a valid task_id or protocol_id provided.*\n- *protocol_id*\n - __Name__: *protocol_id*\n - __Type__: *string*\n - __Description__: *Protocol ID of the protocol to use when creating a*\n *new task, if no task_id.*\n - __Optional__: *True*\n - __Notes__: *Gear requires either task_id OR protocol_id. If neither are*\n *provided, gear will exit and log an error requesting that the gear be*\n *re-run with either a valid task_id or protocol_id provided. If both a*\n *task_id and protocol_id are inputted, gear will strictly*\n *utilize the task_id.*\n- *annotation_description*\n - __Name__: *annotation_description*\n - __Type__: *string*\n - __Description__: *Additional information to be appended to each created annotation's `description` field.*\n - __Optional__: *True*\n- *if_annotations_exist*\n - __Name__: *if_annotations_exist*\n - __Type__: *string*\n - __Description__: *Selected behavior if `task_id` is provided and other annotations*\n *are already connected to the task. Options are `override`, `append`, `exit`.*\n - __Default__: `exit`\n- *assignee*\n - __Name__: *assignee*\n - __Type__: *string*\n - __Description__: *If creating a new task, the Flywheel user the task is to be assigned.*\n *If left blank, the assignee will default to the user running the gear. User ID is the*\n *login email address, i.e \"susannahtrevino@flywheel.io\".*\n - __Optional__: *True*\n\n### Outputs\n\nThis gear outputs OHIF annotations attached to a task container, viewable \nwith the Flywheel Viewer. More information on tasks can be found \n[here](https://docs.flywheel.io/User_Guides/user_introduction_to_read_tasks/).\nPlease note that this gear can only run on Flywheel instances where\nread tasks are enabled. If you do not have read tasks enabled or are\nunsure that your instance is set up for this, please contact your \nFlywheel Representative.\n\n#### Files\n\nNo files are outputted by this gear.\n\n#### Metadata\n\nNo metadata is created or modified by this gear.\n\n### Pre-requisites\n\n#### Prerequisite Gear Runs\n\nNo prerequisite gear runs are required by this gear.\n\n#### Prerequisite Files\n\nNo prerequisite files are required by this gear.\n\n#### Prerequisite Metadata\n\nPrerequisite metadata are not required by this gear.\n\n## Usage\n\n### Description\n\nThis gear takes as input a DICOM SEG with one or more segments. It \nprovides as output OHIF annotation representations of these segmentations.\nThese annotations are stored in a task container as specified by the\n`task_id` or `protocol_id` config. If a task_id is specified, the\nexisting task will be utilized as the container for the annotations. If\nprotocol_id is specified, the gear will create a new task utilizing the\ngiven protocol_id. The annotations are overlaid on the source DICOM.\n\n#### File Specifications\n\nThis gear can be run on a DICOM SEG with one or more segmentations,\nwhere the source DICOM is either found in the same session container\nas the inputted DICOM SEG or inputted explicitly.\n\n#### Known Limitations\n\nThis gear assumes that if Derivation Image Sequence and Source Image\nSequence DICOM tags exist, there is exactly one of each. This gear does\nnot currently handle cases where multiple of one or both tags are present\nin the source DICOM.\n\nOblique images (not axial/sagittal/coronal) are not supported by this gear.\n\n### Workflow\n\n```mermaid\ngraph LR;\n A[DICOM SEG]:::input --> E;\n B[Source DICOM]:::input -.->|optional| E((DICOM-SEG-to-OHIF));\n C[task_id or protocol_id] --> E;\n\n E:::gear --> G[OHIF annotations \\n attached to \\n task container]:::container;\n\n classDef container fill:#57d,color:#fff\n classDef input fill:#7a9,color:#fff\n classDef gear fill:#659,color:#fff\n\n```\n\nDescription of workflow\n\n1. Upload DICOM SEG to acquisition container\n1. Upload source DICOM to acquisition container within the same\nsession as the DICOM SEG\n1. Select DICOM SEG as input to gear\n1. Gear attaches output OHIF annotations to task\n\n### Use Cases\n\n#### Use Case 1: DICOM SEG with gear-identified source DICOM \n\n__*Conditions:*__\n\n- DICOM SEG and source DICOM are uploaded to the same session container\n- Exactly one DICOM within the session container matches the DICOM SEG\n\nAfter inputting the DICOM SEG and beginning the gear run, the gear will\nsearch for the source DICOM within the session container. The gear\nwill then utilize the source DICOM as needed in conjunction with the\nDICOM SEG to create the OHIF annotation output.\n\n#### Use Case 2: DICOM SEG with inputted source DICOM \n\n__*Conditions:*__\n\n- DICOM SEG and source DICOM are uploaded to Flywheel\n- Source DICOM is not in the same session container, or multiple\nDICOMs in the session container match the DICOM SEG\n\nThe DICOM SEG and source DICOM must both be provided as inputs. The\ngear will utilize the inputted source DICOM instead of searching\nfor the file within the session container.\n\n#### Use Case 3: Attaching OHIF annotations to already-existing task\n\n__*Conditions:*__\n\n- Task with which to contain the annotations is already created\n\nBy inputting the `task_id` of the already-created task, this gear will\nconnect all outputted annotations to the designated task.\n\n#### Use Case 4: Comparing two sets of segmentations in OHIF\n\n__*Conditions:*__\n\n- Task with which to contain the annotations is already created\n- Multiple DICOM-SEG files exist for the same source DICOM\n- User wants to compare the two DICOM-SEG annotations\n\nBy running this gear twice with two different DICOM-SEG files and configuring\nthe gear run with the same `task_id` and setting `if_annotations_exist=\"append\"`,\nboth gear runs will add annotations to the same task container. By configuring\n`annotation_description` with contrasting text (i.e. information about how the\nDICOM-SEG was created), these annotations can be better identified while\nutilizing the Flywheel Viewer.\n\n#### Use Case 5: Attaching OHIF annotations to new task with existing protocol\n\n__*Conditions:*__\n\n- New task is needed to contain the annotations\n- Protocol with which to create a new task exists\n\nBy inputting the `protocol_id` of the protocol to be used to create a \nnew task, the gear will initialize a new task with the given protocol,\nallowing protocol configurations to be re-used for each new task.\n\n#### Use Case 6: Attaching OHIF annotations to new task, no existing protocol\n\n__*Conditions:*__\n\n- New task is needed to contain the annotations\n- A protocol with which to create a new task does not yet exist\n\nIn Flywheel, all read tasks require a protocol. This protocol sets a variety\nof configuration options, and without a protocol, any attached annotations\nwould not be viewable within the Flywheel Viewer. \n\nOne way to create a new protocol is via a python script. The below code\nsnippet can be used for this purpose, leveraging FWClient to make API calls:\n\n```python\nfrom fw_client import FWClient\n\nfw = FWClient(api_key=api_key) # Insert your API key here\n\nform_info = {\n \"viewer\": \"OHIF\",\n \"parent\": {\n \"type\": container, # site/project\n \"id\": parent_id # id of container\n },\n \"form\": {} # If desired, a form can be configured here; left blank will initialize the task without an attached form.\n}\n\nform = fw.post('/api/forms', json=form_info)\n\nviewer_info = {\n \"name\": \"DICOM SEG viewer config\", # Can be changed\n \"config\": {} # If desired, viewer config options can be added here; left blank will initialize the default viewer.\n}\n\nviewer = fw.post('/api/viewerconfigs', json=viewer_info)\n\nprotocol_info = {\n \"label\": \"DICOM SEG to OHIF\", # Can be changed\n \"description\": \"Protocol for DICOM SEG to OHIF\", # Can be changed\n \"form_id\": form._id,\n \"viewer_config_id\": viewer._id,\n \"parent\": {\n \"type\": container, # Match the container provided for form_info\n \"id\": parent_id # Match the parent_id provided for form_info\n }\n}\n\nprotocol = fw.post('/api/read_task_protocols', json=protocol_info)\n\nprint(protocol._id)\n```\n\n### Logging\n\nThis gear logs information about the gear run, including configuration settings,\nsegments found within the DICOM SEG, and calls made to the Flywheel API.\nIf the gear run encounters a known error, the gear logs what occurred and, if\napplicable, what to do to fix the error in a subsequent run.\n\n## FAQ\n\n[FAQ.md](docs/faq.md)\n\n## Contributing\n\nFor more information about how to get started contributing to that gear,\ncheckout [CONTRIBUTING.md](CONTRIBUTING.md).\n<!-- markdownlint-disable-file -->\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Flywheel Gear for converting DICOM SEG ROIs to OHIF JSON",
"version": "0.0.4",
"project_urls": {
"Homepage": "https://gitlab.com/flywheel-io/scientific-solutions/gears/dicom-seg-to-ohif",
"Repository": "https://gitlab.com/flywheel-io/scientific-solutions/gears/dicom-seg-to-ohif"
},
"split_keywords": [
"flywheel",
" gears"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "93ed2d6dd45e65b5e6afac60f8f61307b71cb1c8fe7411e9ee243c2642940e4a",
"md5": "7dead2884c8f300f20a0b11b5923aeb1",
"sha256": "926c80491a331e2bfb8b67ca566ab11d07b41ff11c426ab783f5c04255f4e3d5"
},
"downloads": -1,
"filename": "fw_gear_dicom_seg_to_ohif-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7dead2884c8f300f20a0b11b5923aeb1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 16922,
"upload_time": "2024-10-01T17:38:23",
"upload_time_iso_8601": "2024-10-01T17:38:23.183580Z",
"url": "https://files.pythonhosted.org/packages/93/ed/2d6dd45e65b5e6afac60f8f61307b71cb1c8fe7411e9ee243c2642940e4a/fw_gear_dicom_seg_to_ohif-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-01 17:38:23",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "flywheel-io",
"gitlab_project": "scientific-solutions",
"lcname": "fw-gear-dicom-seg-to-ohif"
}
JSON