feat: Added documentation for OHIF-v3 (#2450)
* Added docs with new screenshots * Added doc to architecture * Added documentations to various extension modules * Added more documentation to modes * Added docs to managers * Added docs for services * Fixed deployment docs * Added white labelling documentation * Added i18n docs and measurement export
This commit is contained in:
1 parent
1bf651e763
commit
5643f8f6d2
142 files changed
+5251
-1523
No files matched your search
@@ -0,0 +1,111 @@
|
||||
# DICOM Metadata Store
|
||||
|
||||
|
||||
## Overview
|
||||
`DicomMetaDataStore` is the central location that stores the metadata in `OHIF-v3`. There
|
||||
are several APIs to add study/series/instance metadata and also for getting from the store.
|
||||
DataSource utilize the `DicomMetaDataStore` to add the retrieved metadata to `OHIF Viewer`.
|
||||
|
||||
> In `OHIF-v3` we have significantly changed the architecture of the metadata storage to
|
||||
> provide a much cleaner way of handling metadata-related tasks and services. Classes such as
|
||||
> `OHIFInstanceMetadata`, `OHIFSeriesMetadata` and `OHIFStudyMetadata` has been removed and
|
||||
> replaced with `DicomMetaDataStore`.
|
||||
>
|
||||
|
||||
|
||||
## Events
|
||||
There are two events that get publish in `DicomMetaDataStore`:
|
||||
|
||||
|
||||
| Event | Description |
|
||||
|-----------------|------------------------------------------------------------------------------------------------|
|
||||
| SERIES_ADDED | Fires when all series of one study have added their summary metadata to the `DicomMetaDataStore` |
|
||||
| INSTANCES_ADDED | Fires when all instances of one series have added their metadata to the `DicomMetaDataStore` |
|
||||
|
||||
|
||||
## API
|
||||
Let's find out about the public API for `DicomMetaDataStore` service.
|
||||
|
||||
- `EVENTS`: Object including the events mentioned above. You can subscribe to these events
|
||||
by calling DicomMetaDataStore.subscribe(EVENTS.SERIES_ADDED, myFunction). [Read more about pub/sub pattern here](../pubsub.md)
|
||||
|
||||
- `addInstances(instances, madeInClient = false)`: adds the instances metadata to the store. madeInClient is explained in detail below. After
|
||||
adding to the store it fires the EVENTS.INSTANCES_ADDED.
|
||||
|
||||
- `addSeriesMetadata(seriesSummaryMetadata, madeInClient = false)`: adds series summary metadata. After adding it fires EVENTS.SERIES_ADDED
|
||||
|
||||
- `addStudy(study)`: creates and add study-level metadata to the store.
|
||||
|
||||
- `getStudy(StudyInstanceUID)`: returns the study metadata from the store. It includes all the series and instance metadata in the requested study
|
||||
|
||||
- `getSeries(StudyInstanceUID, SeriesInstanceUID`: returns the series-level metadata for the requested study and series UIDs.
|
||||
|
||||
- `getInstance(StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID)`: returns the instance metadata based on the study, series and sop instanceUIDs.
|
||||
|
||||
- `geteInstanceFromImageId`: returns the instance metadata based on the requested imageId. It searches the store for the instance that has the same imageId.
|
||||
|
||||
|
||||
|
||||
### madeInClient
|
||||
|
||||
Since upon adding the metadata to the store, the relevant events are fired, and there are
|
||||
other services that are subscribed to these events (`HangingProtocolService` or `DisplaySetService`), sometimes
|
||||
we want to add instance metadata but don't want the events to get fired. For instance, when
|
||||
you are caching the data for the next study in advance, you probably don't want to trigger hanging protocol
|
||||
logic, so you set `madeInClient=true` to not fire events.
|
||||
|
||||
|
||||
## Storage
|
||||
As discussed before, there are several API that enables getting metadata from the store and adding to the store.
|
||||
However, it is good to have an understanding of where they get
|
||||
stored and in what format and hierarchy. `_model` is a private variable in the store
|
||||
which holds all the metadata for all studies, series, and instances, and it looks like:
|
||||
|
||||
|
||||
```js
|
||||
// platform/core/src/services/DicomMetadataStore/DicomMetadataStore.js
|
||||
|
||||
const _model = {
|
||||
studies: [
|
||||
{
|
||||
/** Study Metadata **/
|
||||
seriesLists: [
|
||||
{
|
||||
// Series in study from dicom web server 1 (or different backend 1)
|
||||
series: [
|
||||
{
|
||||
// Series 1 Metadata
|
||||
instances: [
|
||||
{
|
||||
// Instance 1 metadata of Series 1
|
||||
},
|
||||
{
|
||||
// Instance 2 metadata of Series 1
|
||||
},
|
||||
/** Other instances metadata **/
|
||||
],
|
||||
},
|
||||
{
|
||||
// Series 2 Metadata
|
||||
instances: [
|
||||
{
|
||||
// Instance 1 metadata of Series 2
|
||||
},
|
||||
{
|
||||
// Instance 2 metadata of Series 1
|
||||
},
|
||||
/** Other instances metadata **/
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
// Series in study from dicom web server 2 (or different backend 2)
|
||||
/** ... **/
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
}
|
||||
|
||||
```
|
||||
@@ -0,0 +1,85 @@
|
||||
# DisplaySet Service
|
||||
|
||||
|
||||
## Overview
|
||||
`DisplaySetService` handles converting the `instanceMetadata` into `DisplaySet` that `OHIF` uses for the visualization. `DisplaySetService` gets initialized in the `Mode.jsx`. During the initialization `SOPClassHandlerIds` of the `modes` gets registered with the `DisplaySetService`.
|
||||
|
||||
> Based on the instanceMetadata's `SOPClassHandlerId`, the correct module from the registered extensions is found by `OHIF` and its `getDisplaySetsFromSeries` runs to create a DisplaySet for the Series.
|
||||
|
||||
|
||||
```js
|
||||
// platform/core/src/services/DisplaySetService/DisplaySetService.js
|
||||
|
||||
init(extensionManager, SOPClassHandlerIds) {
|
||||
this.extensionManager = extensionManager;
|
||||
this.SOPClassHandlerIds = SOPClassHandlerIds;
|
||||
this.activeDisplaySets = [];
|
||||
}
|
||||
```
|
||||
|
||||
in `Mode.jsx`
|
||||
|
||||
```js
|
||||
// platform/viewer/src/routes/Mode/Mode.jsx
|
||||
|
||||
export default function ModeRoute(/** ... **/) {
|
||||
/** ... **/
|
||||
const { DisplaySetService } = servicesManager.services
|
||||
const { sopClassHandlers } = mode
|
||||
/** ... **/
|
||||
useEffect(
|
||||
() => {
|
||||
/** ... **/
|
||||
|
||||
// Add SOPClassHandlers to a new SOPClassManager.
|
||||
DisplaySetService.init(extensionManager, sopClassHandlers)
|
||||
|
||||
/** ... **/
|
||||
}
|
||||
/** ... **/
|
||||
)
|
||||
/** ... **/
|
||||
return <> /** ... **/ </>
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## Events
|
||||
There are three events that get broadcasted in `DisplaySetService`:
|
||||
|
||||
|
||||
|
||||
| Event | Description |
|
||||
| -------------------- | ---------------------------------------------------- |
|
||||
| DISPLAY_SETS_ADDED | Fires a displayset is added to the displaysets cache |
|
||||
| DISPLAY_SETS_CHANGED | Fires when a displayset is changed |
|
||||
| DISPLAY_SETS_REMOVED | Fires when a displayset is removed |
|
||||
|
||||
|
||||
|
||||
|
||||
## API
|
||||
Let's find out about the public API for `DisplaySetService`.
|
||||
|
||||
- `EVENTS`: Object including the events mentioned above. You can subscribe to these events
|
||||
by calling DisplaySetService.subscribe(EVENTS.DISPLAY_SETS_CHANGED, myFunction). [Read more about pub/sub pattern here](../pubsub.md)
|
||||
|
||||
- `makeDisplaySets(input, { batch, madeInClient, settings } = {}`): Creates displaySet for the provided
|
||||
array of instances metadata. Each display set gets a random UID assigned.
|
||||
|
||||
- `input`: Array of instances Metadata
|
||||
- `batch = false`: If you need to pass array of arrays of instances metadata to have a batch creation
|
||||
- `madeInClient = false`: Disables the events firing
|
||||
- `settings = {}`: Hanging protocol viewport or rendering settings. For instance, setting the initial `voi`, or activating a tool upon
|
||||
displaySet rendering. [Read more about hanging protocols settings here](./HangingProtocolService.md#Settings)
|
||||
|
||||
|
||||
- `getDisplaySetByUID`: Returns the displaySet based on the DisplaySetUID.
|
||||
|
||||
- `getDisplaySetForSOPInstanceUID`: Returns the displaySet that includes an image with the provided SOPInstanceUID
|
||||
|
||||
- `getActiveDisplaySets`: Returns the active displaySets
|
||||
|
||||
- `deleteDisplaySet`: Deletes the displaySets from the displaySets cache
|
||||
@@ -0,0 +1,324 @@
|
||||
# Hanging Protocol Service
|
||||
|
||||
## Overview
|
||||
`HangingProtocolService` is a migration of the `OHIF-v1` hanging protocol engine.
|
||||
This service handles the arrangement of the images in the viewport.
|
||||
In short, the registered protocols will get matched with the Series that are available
|
||||
for the series. Each protocol gets a point, and they are ranked. The winning protocol gets
|
||||
applied and its settings run for the viewports.
|
||||
|
||||
You can read more about hanging protocols [here](http://dicom.nema.org/dicom/Conf-2005/Day-2_Selected_Papers/B305_Morgan_HangProto_v1.pdf). In short
|
||||
with `OHIF-v3` hanging protocols you can:
|
||||
|
||||
- Define what layout of the viewport should the viewer starts with (2x2 layout)
|
||||
- Define which series gets displayed in which position of the layout
|
||||
- Apply certain initial viewport settings; e.g., inverting the contrast
|
||||
- Enable certain tools based on what series are displayed: link prostate T2 and ADC MRI.
|
||||
|
||||
|
||||
|
||||
|
||||
## Skeleton of A Hanging Protocol
|
||||
You can find the skeleton of the hanging protocols here:
|
||||
|
||||
```js
|
||||
const deafultProtocol = {
|
||||
id: 'defaultProtocol',
|
||||
locked: true,
|
||||
hasUpdatedPriorsInformation: false,
|
||||
name: 'Default',
|
||||
createdDate: '2021-02-23T19:22:08.894Z',
|
||||
modifiedDate: '2021-02-23T19:22:08.894Z',
|
||||
availableTo: {},
|
||||
editableBy: {},
|
||||
protocolMatchingRules: [],
|
||||
stages: [
|
||||
{
|
||||
id: 'nwzau7jDkEkL8djfr',
|
||||
name: 'oneByOne',
|
||||
viewportStructure: {
|
||||
type: 'grid',
|
||||
properties: {
|
||||
rows: 1,
|
||||
columns: 1,
|
||||
},
|
||||
},
|
||||
viewports: [
|
||||
{
|
||||
viewportSettings: [],
|
||||
imageMatchingRules: [],
|
||||
seriesMatchingRules: [],
|
||||
studyMatchingRules: [],
|
||||
},
|
||||
],
|
||||
createdDate: '2021-02-23T19:22:08.894Z',
|
||||
},
|
||||
],
|
||||
numberOfPriorsReferenced: -1,
|
||||
};
|
||||
```
|
||||
|
||||
Let's discuss each property in depth.
|
||||
|
||||
|
||||
|
||||
|
||||
- `id`: unique identifier for the protocol
|
||||
|
||||
- `protocolMatchingRules`: A list of criteria for the protocol along with the provided points for ranking.
|
||||
|
||||
- `weight`: weight for the matching rule. Eventually, all the registered protocols get sorted based on the weights, and the winning
|
||||
protocol gets applied to the viewer.
|
||||
- `attriubte`: tag that needs to be matched against. This can be either Study-level metadata or a custom attribute. [Learn more about custom attribute matching](#custom-attribute)
|
||||
|
||||
- `constraint`: the constraint that needs to be satisfied for the attribute. It accept a `validator` which can be
|
||||
[`equals`, `doesNotEqual`, `contains`, `doesNotContain`, `startsWith`, `endsWidth`]
|
||||
|
||||
A sample of the matching rule is:
|
||||
|
||||
```js
|
||||
{
|
||||
id: 'wauZK2QNEfDPwcAQo',
|
||||
weight: 1,
|
||||
attribute: 'StudyInstanceUID',
|
||||
constraint: {
|
||||
equals: {
|
||||
value: '1.3.6.1.4.1.25403.345050719074.3824.20170125112931.11',
|
||||
},
|
||||
},
|
||||
required: true,
|
||||
}
|
||||
```
|
||||
|
||||
- `stages`: Each protocol can defined one or more stages. Each stage defines a certain layout and viewport rules.
|
||||
Therefore, the `stages` property is array of objects, each object being one stage.
|
||||
|
||||
- `viewportStructure`: Defines the layout of the viewer. You can define the number of `rows` and `columns`.
|
||||
There should be `rows * columns` number of viewport configuration in the `viewports` property. Note that order of viewports are rows first then columns.
|
||||
|
||||
- `viewportSettings`: custom settings to be applied to the viewport. This can be a `voi` being applied
|
||||
to the viewer or a tool to get enabled. We will discuss viewport-specific settings [below](#viewport-settings)
|
||||
|
||||
- `imageMatchingRules (comming soon)`: setting the image slice for the viewport.
|
||||
|
||||
- `seriesMatchingRules`: the most important rule that matches series in the viewport. For instance, the following stage
|
||||
configuration will create a one-by-two layout and put the series whose description contains `t2` on the left, and a series with
|
||||
description that contains `adc` on the right. (order of viewports are rows, first then columns)
|
||||
|
||||
```js
|
||||
stages: [
|
||||
{
|
||||
id: 'hYbmMy3b7pz7GLiaT',
|
||||
name: 'oneByThree',
|
||||
viewportStructure: {
|
||||
type: 'grid',
|
||||
properties: {
|
||||
rows: 1,
|
||||
columns: 2,
|
||||
},
|
||||
},
|
||||
viewports: [
|
||||
// viewport 1
|
||||
{
|
||||
viewportSettings: [],
|
||||
imageMatchingRules: [],
|
||||
seriesMatchingRules: [
|
||||
{
|
||||
id: 'vSjk7NCYjtdS3XZAw',
|
||||
weight: 1,
|
||||
attribute: 'SeriesDescription',
|
||||
constraint: {
|
||||
contains: {
|
||||
value: 't2',
|
||||
},
|
||||
},
|
||||
required: false,
|
||||
},
|
||||
],
|
||||
studyMatchingRules: [],
|
||||
},
|
||||
// viewport 2
|
||||
{
|
||||
viewportSettings: [],
|
||||
imageMatchingRules: [],
|
||||
seriesMatchingRules: [
|
||||
{
|
||||
id: 'vSjk7NCYjtdS3XZAw',
|
||||
weight: 1,
|
||||
attribute: 'SeriesDescription',
|
||||
constraint: {
|
||||
contains: {
|
||||
value: 'ADC',
|
||||
},
|
||||
},
|
||||
required: true,
|
||||
},
|
||||
],
|
||||
studyMatchingRules: [],
|
||||
},
|
||||
],
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Events
|
||||
There are two events that get publish in `HangingProtocolService`:
|
||||
|
||||
|
||||
| Event | Description |
|
||||
| ------------ | -------------------------------------------------------------------- |
|
||||
| NEW_LAYOUT | Fires when a new layout is requested by the `HangingProtocolService` |
|
||||
| STAGE_CHANGE | Fires when the the stage is changed in the hanging protocols |
|
||||
|
||||
|
||||
## API
|
||||
|
||||
- `getState`: returns an array: `[matchDetails, hpAlreadyApplied]`:
|
||||
|
||||
- `matchDetails`: matching details for the series
|
||||
- `hpAlreadyApplied`: An array which tracks whether HPServices has been applied on each viewport.
|
||||
|
||||
- `addProtocols`: adds provided protocols to the list of registered protocols for matching
|
||||
|
||||
- `run(studyMetaData, protocol)`: runs the HPService with the provided studyMetaData and optional protocol.
|
||||
If protocol is not given, HP Matching engine will search all the registered protocols for the best matching one based on the constraints.
|
||||
|
||||
- `addCustomAttribute`: adding a custom attribute for matching. (see below)
|
||||
|
||||
- `addCustomViewportSetting`: adding a custom setting to a viewport (initial `voi`). Below, we explain
|
||||
in detail how to add custom viewport settings via protocol definitions. `addCustomViewportSetting` is another way to set
|
||||
these settings which is exposed by API
|
||||
|
||||
-
|
||||
|
||||
Default initialization of the modes handles running the `HangingProtocolService`
|
||||
|
||||
## Custom Attribute
|
||||
In some situations, you might want to match based on a custom attribute and not the DICOM tags. For instance,
|
||||
if you have assigned a `timepointId` to each study and you want to match based on it.
|
||||
Good news is that, in `OHIF-v3` you can define you custom attribute and use it for matching.
|
||||
|
||||
There are various ways that you can let `HangingProtocolService` know of you custom attribute.
|
||||
We will show how to add it inside the mode configuration.
|
||||
|
||||
|
||||
```js
|
||||
const deafultProtocol = {
|
||||
id: 'defaultProtocol',
|
||||
/** ... **/
|
||||
protocolMatchingRules: [
|
||||
{
|
||||
id: 'vSjk7NCYjtdS3XZAw',
|
||||
weight: 3,
|
||||
attribute: 'timepoint',
|
||||
constraint: {
|
||||
equals: {
|
||||
value: 'first',
|
||||
},
|
||||
},
|
||||
required: false,
|
||||
},
|
||||
],
|
||||
stages: [
|
||||
/** ... **/
|
||||
],
|
||||
numberOfPriorsReferenced: -1,
|
||||
}
|
||||
|
||||
// Custom function for custom attribute
|
||||
const getTimePointUID = (metaData) => {
|
||||
// requesting the timePoint Id
|
||||
return myBackEndAPI(metaData)
|
||||
}
|
||||
|
||||
export default function mode() {
|
||||
return {
|
||||
id: 'myMode',
|
||||
/** .. **/
|
||||
routes: [
|
||||
{
|
||||
path: 'myModeRoute',
|
||||
init: async ({}) => {
|
||||
const { DicomMetadataStore, HangingProtocolService } =
|
||||
servicesManager.services
|
||||
|
||||
const onSeriesAdded = ({
|
||||
StudyInstanceUID,
|
||||
madeInClient = false,
|
||||
}) => {
|
||||
const studyMetadata = DicomMetadataStore.getStudy(StudyInstanceUID)
|
||||
|
||||
// Adding custom attribute to the hangingprotocol
|
||||
HangingProtocolService.addCustomAttribute(
|
||||
'timepoint',
|
||||
'timepoint',
|
||||
(metaData) => getFirstMeasurementSeriesInstanceUID(metaData)
|
||||
)
|
||||
|
||||
HangingProtocolService.run(studyMetadata)
|
||||
}
|
||||
|
||||
DicomMetadataStore.subscribe(
|
||||
DicomMetadataStore.EVENTS.SERIES_ADDED,
|
||||
onSeriesAdded
|
||||
)
|
||||
},
|
||||
},
|
||||
],
|
||||
/** ... **/
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Viewport Settings
|
||||
You can define custom settings to be applied to each viewport. There
|
||||
are two types of settings:
|
||||
|
||||
- `viewport settings`: Currently we support two viewport settings
|
||||
|
||||
- `voi`: applying an initial `voi` by setting the windowWidth and windowCenter
|
||||
- `inverted`: inverting the viewport color (e.g., for PET images)
|
||||
|
||||
- `props settings`: Running commands after the first render; e.g., enabling the link tool
|
||||
|
||||
|
||||
Examples of each settings are :
|
||||
|
||||
```js
|
||||
viewportSettings: [
|
||||
{
|
||||
options: {
|
||||
itemId: 'SyncScroll',
|
||||
interactionType: 'toggle',
|
||||
commandName: 'toggleSynchronizer',
|
||||
commandOptions: { toggledState: true },
|
||||
},
|
||||
commandName: 'setToolActive',
|
||||
type: 'props',
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```js
|
||||
viewportSettings: [
|
||||
{
|
||||
options: {
|
||||
voi: {
|
||||
windowWidth: 400,
|
||||
windowCenter: 40,
|
||||
},
|
||||
},
|
||||
commandName: '',
|
||||
type: 'viewport',
|
||||
},
|
||||
]
|
||||
```
|
||||
@@ -0,0 +1,156 @@
|
||||
# Measurement Service
|
||||
|
||||
|
||||
## Overview
|
||||
`MeasurementService` handles the internal measurement representation inside `OHIF` platform.
|
||||
Developers can add their custom `sources` with `mappers` to enable adding measurements inside OHIF.
|
||||
Currently, we are maintaining `CornerstoneTools` annotations and corresponding mappers can be found
|
||||
inside the `cornerstone` extension. However, `MeasurementService` can be configured to work with any
|
||||
custom tools given that its `mappers` is added to the `MeasurementService`.
|
||||
We can see the overall architecture of the `MeasurementService` below:
|
||||
|
||||
|
||||
|
||||

|
||||
|
||||
|
||||
## Events
|
||||
There are seven events that get publish in `MeasurementService`:
|
||||
|
||||
|
||||
|
||||
| Event | Description |
|
||||
| --------------------- | ------------------------------------------------------ |
|
||||
| MEASUREMENT_UPDATED | Fires when a measurement is updated |
|
||||
| MEASUREMENT_ADDED | Fires when a new measurement is added |
|
||||
| RAW_MEASUREMENT_ADDED | Fires when a raw measurement is added (e.g., dicom-sr) |
|
||||
| MEASUREMENT_REMOVED | Fires when a measurement is removed |
|
||||
| MEASUREMENTS_CLEARED | Fires when all measurements are deleted |
|
||||
| JUMP_TO_MEASUREMENT | Fires when a measurement is requested to be jump to |
|
||||
|
||||
|
||||
|
||||
## API
|
||||
|
||||
- `getMeasurements`: returns array of measurements
|
||||
|
||||
- `getMeasurement(id)`: returns the corresponding measurement based on the provided Id.
|
||||
|
||||
- `remove(id, source)`: removes a measurement and broadcasts the `MEASUREMENT_REMOVED` event.
|
||||
|
||||
- `clearMeasurements`: removes all measurements and broadcasts `MEASUREMENTS_CLEARED` event.
|
||||
|
||||
- `createSource(name, version)`: creates a new measurement source, generates a uid and adds it to the `sources` property of the service.
|
||||
|
||||
- `addMapping(source, definition, matchingCriteria, toSourceSchema, toMeasurementSchema)`: adds a new measurement matching criteria along with mapping functions.
|
||||
We will learn more about [source/mappers below](#source--mappers)
|
||||
|
||||
- `update`: updates the measurement details and fires `MEASUREMENT_UPDATED`
|
||||
|
||||
- `addRawMeasurement(source,definition,data,toMeasurementSchema,dataSource = {}` : adds a raw measurement into a source so that it may be
|
||||
converted to/from annotation in the same way. E.g. import serialized data
|
||||
of the same form as the measurement source. Fires `MEASUREMENT_UPDATED` or `MEASUREMENT_ADDED`.
|
||||
Note that, `MeasurementService` handles finding the correct mapper upon new measurements; however, `addRawMeasurement` provides more flexibility.
|
||||
You can take a look into its usage in `dicom-sr` extension.
|
||||
|
||||
- `source`: The measurement source instance.
|
||||
- `definition`: The source definition you want to add the measurement to.
|
||||
- `data`: The data you wish to add to the source.
|
||||
- `toMeasurementSchema`: A function to get the `data` into the same shape as the source definition.
|
||||
|
||||
- `jumpToMeasurement(viewportIndex, id)`: calls the listeners who have subscribed to `JUMP_TO_MEASUREMENT`.
|
||||
|
||||
|
||||
|
||||
|
||||
## Source / Mappers
|
||||
To create a custom measurement source and relevant mappers for each tool, you can take a look
|
||||
at the `init.js` inside the `cornerstone` extension. In which we are registering our
|
||||
`CornerstoneTools-v4` measurement source to MeasurementService. Let's take a peek at the
|
||||
*simplified* implementation together. To achieve this, for each tool, we need to
|
||||
provide three mappers:
|
||||
|
||||
- `matchingCriteria`: criteria used for finding the correct mapper for the drawn tool.
|
||||
- `toAnnotation`: tbd
|
||||
- `toMeasurement`: a function that converts the tool data to OHIF internal representation of measurement data.
|
||||
|
||||
|
||||
```js
|
||||
// extensions/cornerstone/src/utils/measurementServiceMappings/Length.js
|
||||
|
||||
function toMeasurement(
|
||||
csToolsAnnotation,
|
||||
DisplaySetService,
|
||||
getValueTypeFromToolType
|
||||
) {
|
||||
const { element, measurementData } = csToolsAnnotation
|
||||
|
||||
/** ... **/
|
||||
|
||||
const {
|
||||
SOPInstanceUID,
|
||||
FrameOfReferenceUID,
|
||||
SeriesInstanceUID,
|
||||
StudyInstanceUID,
|
||||
} = getSOPInstanceAttributes(element)
|
||||
|
||||
const displaySet = DisplaySetService.getDisplaySetForSOPInstanceUID(
|
||||
SOPInstanceUID,
|
||||
SeriesInstanceUID
|
||||
)
|
||||
|
||||
/** ... **/
|
||||
return {
|
||||
id: measurementData.id,
|
||||
SOPInstanceUID,
|
||||
FrameOfReferenceUID,
|
||||
referenceSeriesUID: SeriesInstanceUID,
|
||||
referenceStudyUID: StudyInstanceUID,
|
||||
displaySetInstanceUID: displaySet.displaySetInstanceUID,
|
||||
label: measurementData.label,
|
||||
description: measurementData.description,
|
||||
unit: measurementData.unit,
|
||||
length: measurementData.length,
|
||||
type: getValueTypeFromToolType(tool),
|
||||
points: getPointsFromHandles(measurementData.handles),
|
||||
}
|
||||
}
|
||||
|
||||
//////////////////////////////////////////
|
||||
|
||||
// extensions/cornerstone/src/init.js
|
||||
|
||||
const Length = {
|
||||
toAnnotation,
|
||||
toMeasurement,
|
||||
matchingCriteria: [
|
||||
{
|
||||
valueType: MeasurementService.VALUE_TYPES.POLYLINE,
|
||||
points: 2,
|
||||
},
|
||||
],
|
||||
}
|
||||
|
||||
const _initMeasurementService = (MeasurementService, DisplaySetService) => {
|
||||
/** ... **/
|
||||
|
||||
const csToolsVer4MeasurementSource = MeasurementService.createSource(
|
||||
'CornerstoneTools',
|
||||
'4'
|
||||
);
|
||||
|
||||
/* Mappings */
|
||||
MeasurementService.addMapping(
|
||||
csToolsVer4MeasurementSource,
|
||||
'Length',
|
||||
Length.matchingCriteria,
|
||||
toAnnotation,
|
||||
toMeasurement
|
||||
);
|
||||
|
||||
/** Other tools **/
|
||||
return csToolsVer4MeasurementSource;
|
||||
};
|
||||
|
||||
|
||||
```
|
||||
@@ -0,0 +1,219 @@
|
||||
# Toolbar Service
|
||||
|
||||
|
||||
## Overview
|
||||
`ToolbarService` handles the toolbar section buttons, and what happens when a button is clicked by
|
||||
the user.
|
||||
|
||||
|
||||
<div style="padding:62.5% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/547957214?badge=0&autopause=0&player_id=0&app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen style="position:absolute;top:0;left:0;width:100%;height:100%;" title="Toolbar"></iframe></div><script src="https://player.vimeo.com/api/player.js"></script>
|
||||
|
||||
|
||||
## Events
|
||||
|
||||
|
||||
| Event | Description |
|
||||
| ----------------------- | ---------------------------------------------------------------------- |
|
||||
| TOOL_BAR_MODIFIED | Fires when a button is added/removed to the toolbar |
|
||||
| TOOL_BAR_STATE_MODIFIED | Fires when an interaction happens and ToolbarService state is modified |
|
||||
|
||||
|
||||
|
||||
|
||||
## API
|
||||
|
||||
- `recordInteraction(interaction)`: executes the provided interaction which is an object providing the following properties to the ToolbarService:
|
||||
|
||||
- `interactionType`: can be `tool`, `toggle` and `action`. We will discuss more each type below.
|
||||
- `itemId`: tool name
|
||||
- `groupId`: the Id for the tool button group; e.g., `Wwwc` which holds presets.
|
||||
- `commandName`: if tool has a command attached to run
|
||||
- `commandOptions`: arguments for the command.
|
||||
|
||||
- `reset`: reset the state of the toolbarService, set the primary tool to be `Wwwc` and unsubscribe tools that have registered their functions.
|
||||
|
||||
- `addButtons`: add the button definition to the service. [See below for button definition](#button-definitions).
|
||||
|
||||
- `setButtons`: sets the buttons defined in the service. It overrides all the previous buttons
|
||||
|
||||
- `getActiveTools`: returns the active tool + all the toggled-on tools
|
||||
|
||||
|
||||
|
||||
## State
|
||||
ToolbarService has an internal state that gets updated per tool interaction and tracks the
|
||||
active toolId, state of the buttons that have toggled state, and the group buttons and which tool
|
||||
in each group is active.
|
||||
|
||||
|
||||
```js
|
||||
state = {
|
||||
primaryToolId: 'Wwwc',
|
||||
toggles: {
|
||||
/* id: true/false */
|
||||
},
|
||||
groups: {
|
||||
/* track most recent click per group...*/
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Interaction type
|
||||
There are three main types that a tool can have which is defined in the interaction object.
|
||||
|
||||
- `tool`: setting a tool to be active; e.g., measurement tools
|
||||
- `toggle`: toggling state of a tool; e.g., viewport link (sync)
|
||||
- `action`: performs a registered action outside of the ToolbarService; e.g., capture
|
||||
|
||||
A *simplified* implementation of the ToolbarService is:
|
||||
|
||||
|
||||
```js
|
||||
export default class ToolBarService {
|
||||
/** ... **/
|
||||
recordInteraction(interaction) {
|
||||
/** ... **/
|
||||
switch (interactionType) {
|
||||
case 'action': {
|
||||
break
|
||||
}
|
||||
case 'tool': {
|
||||
this.state.primaryToolId = itemId
|
||||
|
||||
commandsManager.runCommand('setToolActive', interaction.commandOptions)
|
||||
break
|
||||
}
|
||||
case 'toggle': {
|
||||
this.state.toggles[itemId] =
|
||||
this.state.toggles[itemId] === undefined
|
||||
? true
|
||||
: !this.state.toggles[itemId]
|
||||
interaction.commandOptions.toggledState = this.state.toggles[itemId]
|
||||
break
|
||||
}
|
||||
default:
|
||||
throw new Error(`Invalid interaction type: ${interactionType}`)
|
||||
}
|
||||
/** ... **/
|
||||
}
|
||||
/** ... **/
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Button Definitions
|
||||
|
||||
The simplest toolbarButtons definition has the following properties:
|
||||
|
||||

|
||||
|
||||
```js
|
||||
{
|
||||
id: 'Zoom',
|
||||
type: 'ohif.radioGroup',
|
||||
props: {
|
||||
type: 'tool',
|
||||
icon: 'tool-zoom',
|
||||
label: 'Zoom',
|
||||
commandOptions: { toolName: 'Zoom' },
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
|
||||
|
||||
| property | description | values |
|
||||
| ---------------- | ----------------------------------------------------------------- | ----------------------------------------- |
|
||||
| `id` | Unique string identifier for the definition | \* |
|
||||
| `label` | User/display friendly to show in UI | \* |
|
||||
| `icon` | A string name for an icon supported by the consuming application. | \* |
|
||||
| `type` | Used to determine the button's behaviour | "tool", "toggle", "action" |
|
||||
| `commandName` | (optional) The command to run when the button is used. | Any command registered by a `CommandModule` |
|
||||
| `commandOptions` | (optional) Options to pass the target `commandName` | \* |
|
||||
|
||||
|
||||
There are three main types of toolbar buttons:
|
||||
|
||||
- `tool`: buttons that enable a tool by running the `setToolActive` command with the `commandOptions`
|
||||
- `toggle`: buttons that acts as a toggle: e.g., linking viewports
|
||||
- `action`: buttons that executes an action: e.g., capture button to save screenshot
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Nested Buttons
|
||||
You can use the `ohif.splitButton` type to build a button with extra tools in the dropdown.
|
||||
|
||||
- First you need to give your `primary` tool definition to the split button
|
||||
- the `secondary` properties can be a simple arrow down (`chevron-down` icon)
|
||||
- For adding the extra tools add them to the `items` list.
|
||||
|
||||
You can see below how `longitudinal` mode is using the available toolbarModule to create
|
||||
`MeasurementTools` nested button
|
||||
|
||||

|
||||
|
||||
```js
|
||||
// modes/longitudinal/src/toolbarButtons.js
|
||||
|
||||
{
|
||||
id: 'MeasurementTools',
|
||||
type: 'ohif.splitButton',
|
||||
props: {
|
||||
groupId: 'MeasurementTools',
|
||||
isRadio: true,
|
||||
primary: {
|
||||
id: 'Length',
|
||||
icon: 'tool-length',
|
||||
label: 'Length',
|
||||
type: 'tool',
|
||||
commandOptions: {
|
||||
toolName: 'Length',
|
||||
}
|
||||
},
|
||||
secondary: {
|
||||
icon: 'chevron-down',
|
||||
label: '',
|
||||
isActive: true,
|
||||
tooltip: 'More Measure Tools',
|
||||
},
|
||||
items: [
|
||||
// Length tool
|
||||
{
|
||||
id: 'Length',
|
||||
icon: 'tool-length',
|
||||
label: 'Length',
|
||||
type: 'tool',
|
||||
commandOptions: {
|
||||
toolName: 'Length',
|
||||
}
|
||||
},
|
||||
// Bidirectional tool
|
||||
{
|
||||
id: 'Bidirectional',
|
||||
icon: 'tool-bidirectional',
|
||||
label: 'Length',
|
||||
type: 'tool',
|
||||
commandOptions: {
|
||||
toolName: 'Bidirectional',
|
||||
}
|
||||
},
|
||||
// Ellipse tool
|
||||
{
|
||||
id: 'EllipticalRoi',
|
||||
icon: 'tool-elipse',
|
||||
label: 'Ellipse',
|
||||
type: 'tool',
|
||||
commandOptions: {
|
||||
toolName: 'EllipticalRoi',
|
||||
}
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,65 @@
|
||||
# Services (default)
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Example](#example)
|
||||
|
||||
## Overview
|
||||
|
||||
Services are a work in progress. As we are still in the progress of creating a
|
||||
non-ui maintained service, this usage may change.
|
||||
|
||||
<div style="text-align: center;">
|
||||
<a href="/assets/img/services.png">
|
||||
<img src="/assets/img/services.png" alt="UI Services Diagram" style="margin: 0 auto; max-width: 500px;" />
|
||||
</a>
|
||||
<div><i>Diagram showing relationship between React Context and UI Service</i></div>
|
||||
</div>
|
||||
|
||||
## Example
|
||||
|
||||
The simplest service return a new object that has a `name` property, and
|
||||
methods/properties that give the service its functionality. The "Factory
|
||||
Function" that creates the service is provided with the implementation (this is
|
||||
slightly different for UI Services).
|
||||
|
||||
```js
|
||||
const _speak = () => {
|
||||
console.warn('Speak is not implemented');
|
||||
};
|
||||
|
||||
/**
|
||||
* Factory function to create `HelloWorldService`
|
||||
*
|
||||
* @param {object} implementation
|
||||
* @param {function} implementation.speak - Speak's implementation
|
||||
* @returns HelloWorldService
|
||||
*/
|
||||
export default function createHelloWorldService({ speak }) {
|
||||
return {
|
||||
name: 'HelloWorldService',
|
||||
speak: speak || _speak,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
A service, once created, can be registered with the `ServicesManager` to make it
|
||||
accessible to extensions. Similarly, the application code can access named
|
||||
services from the `ServicesManager`.
|
||||
|
||||
```js
|
||||
// In the application
|
||||
const speak = () => {
|
||||
window.alert('HELLO WORLD');
|
||||
};
|
||||
const HelloWorldService = createHelloWorldService({ speak });
|
||||
const servicesManager = new ServicesManager();
|
||||
|
||||
servicesManager.registerService(HelloWorldService);
|
||||
|
||||
// In an extension
|
||||
const { HelloWorldService } = servicesManager.services;
|
||||
|
||||
if (HelloWorldService) {
|
||||
HelloWorldService.speak();
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,54 @@
|
||||
# Services (default)
|
||||
|
||||
|
||||
|
||||
## Overview
|
||||
Data services are the first category of services which deal with handling non-ui related state
|
||||
Each services have their own internal state which they handle.
|
||||
|
||||
|
||||
> We have replaced the *redux* store. Instead we have introduced various services and a pub/sub pattern to subscribe and run, which makes the `OHIF-v3` architecture nice and clean.
|
||||
|
||||
|
||||
We maintain the following non-ui Services:
|
||||
|
||||
- [DicomMetadata Store](./../data/DicomMetadataStore.md)
|
||||
- [DisplaySet Service](./../data/DisplaySetService.md)
|
||||
- [Hanging Protocol Service](../data/HangingProtocolService.md)
|
||||
- [Toolbar Service](../data/ToolbarService.md)
|
||||
- [Measurement Service](../data/MeasurementService.md)
|
||||
|
||||
|
||||
|
||||
|
||||
## Service Architecture
|
||||
|
||||

|
||||
|
||||
|
||||
> We have explained services and how to create a custom service in the [`ServiceManager`](../../managers/service.md) section of the docs
|
||||
|
||||
To recap: The simplest service return a new object that has a `name` property, and `Create` method which instantiate the service class. The "Factory
|
||||
Function" that creates the service is provided with the implementation (this is
|
||||
slightly different for UI Services).
|
||||
|
||||
```js
|
||||
// extensions/customExtension/src/services/backEndService/index.js
|
||||
import backEndService from './backEndService';
|
||||
|
||||
export default function WrappedBackEndService(serviceManager) {
|
||||
return {
|
||||
name: 'myService',
|
||||
create: ({ configuration = {} }) => {
|
||||
return new backEndService(serviceManager);
|
||||
},
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
A service, once created, can be registered with the `ServicesManager` to make it
|
||||
accessible to extensions. Similarly, the application code can access named
|
||||
services from the `ServicesManager`.
|
||||
|
||||
|
||||
[Read more of how to design a new custom service and register it](../../managers/service.md)
|
||||
Reference in new issue
Block a user