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:
Alireza authored and GitHub committed 2021-06-15 11:15:29 -04:00
1 parent 1bf651e763
commit 5643f8f6d2
142 files changed
+5251 -1523

No files matched your search

+39 -72
View File
@@ -1,13 +1,18 @@
# Module: Commands
- [Overview](#overview)
- [Command Definitions](#command-definitions)
- [Commands Manager](#commands-manager)
- [Instantiating](#instatiating)
- [Public API](#public-api)
- [Contexts](#contexts)
- [Module: Commands](#module-commands)
- [Overview](#overview)
- [Command Definitions](#command-definitions)
- [Command Behavior](#command-behavior)
- [`CommandsManager` Public API](#commandsmanager-public-api)
- [Contexts](#contexts)
## Overview
`CommandsModule` includes list of arbitrary functions. These may activate tools, communicate with a server, open a modal, etc.
The significant difference between `OHIF-v3` and `OHIF-v2` is that in `v3` a `mode` defines
its toolbar, and which commands each tool call is inside in its toolDefinition
An extension can register a Commands Module by defining a `getCommandsModule`
method. The Commands Module allows us to register one or more commands scoped to
@@ -17,69 +22,55 @@ characteristics that make them tremendously powerful:
- Multiple implementations for the same command can be defined
- Only the correct command's implementation will be run, dependent on the
application's "context"
- Commands can be called from extensions, modules, and the consuming application
- Commands are used by hotkeys, toolbar buttons and render settings
Here is a simple example commands module:
```js
export default {
id: 'example-commands-module',
/**
* @param {object} params
* @param {ServicesManager} params.servicesManager
* @param {CommandsManager} params.commandsManager
*/
getCommandsModule({ servicesManager, commandsManager }) {
return {
definitions: {
sayHello: {
commandFn: ({ words }) => {
console.log(words);
},
options: { words: 'Hello!' },
},
const getCommandsModule = () => ({
definitions: {
exampleActionDef: {
commandFn: ({ param1 }) => {
console.log(`param1's value is: ${param1}`);
},
defaultContext: 'VIEWER',
};
// storeContexts: ['viewports'],
options: { param1: 'param1' },
context: 'VIEWER', // optional
},
},
};
defaultContext: 'ACTIVE_VIEWPORT::DICOMSR',
});
```
Each definition returned by the Commands Module is registered to the
`ExtensionManager`'s `CommandsManager`.
> `storeContexts` has been removed in `OHIF-v3` and now modules have access to all commands and services. This change enables support for user-registered services.
## Command Definitions
The command definition consists of a named command (`myCommandName` below) and a
The command definition consists of a named command (`exampleActionDef` below) and a
`commandFn`. The command name is used to call the command, and the `commandFn`
is the "command" that is actioned.
is the "command" that is actioned. T
```js
myCommandName: {
commandFn: ({ viewports, other, options }) => { },
storeContexts: ['viewports'],
options: { words: 'Just kidding! Goodbye!' },
context: 'ACTIVE_VIEWPORT::CORNERSTONE',
exampleActionDef: {
commandFn: ({ param1, options }) => { },
options: { param1: 'measurement' },
context: 'DEFAULT',
}
```
| Property | Type | Description |
| --------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `commandFn` | func | The function to call when command is run. Receives `options` and `storeContexts`. |
| `storeContexts` | string[] | (optional) Expected state objects to be passed in as props. Located using `getAppState` fn defined at `CommandsManager`'s instatiation. |
| `options` | object | (optional) Arguments to pass at the time of calling to the `commandFn` |
| `context` | string[] or string | (optional) Overrides the `defaultContext`. Let's us know if command is currently "available" to be run. |
## Command Behavior
**I have many similar commands. How can I share their `commandFn` and make it
reusable?**
This is where `storeContexts` and `options` come in. We use these in our
`setToolActive` command. `storeContexts` helps us identify our `activeViewport`,
and `options` allow us to pass in the name of a tool we would like to set as
active.
**If there are multiple valid commands for the application's active contexts**
@@ -93,45 +84,21 @@ active.
- When to use: a `hotkey` (like "invert") that doesn't make sense for the
current viewport (PDF or HTML)
## `CommandsManager`
The `CommandsManager` is a class defined in the `@ohif/core` project. A single
instance of it should be defined in the consuming application, and it should be
used when constructing the `ExtensionManager`.
### Instantiating
When we instantiate the `CommandsManager`, we need to pass it two methods:
- `getAppState` - Should return the application's state when called
- `getActiveContexts` - Should return the application's active contexts when
called
These methods are used internally to help determine which commands are currently
valid, and how to provide them with any state they may need at the time they are
called.
```js
const commandsManager = new CommandsManager({
getAppState,
getActiveContexts,
});
```
### Public API
## `CommandsManager` Public API
If you would like to run a command in the consuming app or an extension, you can
use one of the following methods:
use `CommandsManager.runCommand(commandName, options = {}, contextName)`
```js
// Returns all commands for a given context
commandsManager.getContext('string');
// Attempts to run a command
// Run a command, it will run all the `speak` commands in all contexts
commandsManager.runCommand('speak', { command: 'hello' });
// Run command, but override the active contexts
commandsManager.runCommand('speak', { command: 'hello' }, ['VIEWER']);
// Run command, from Default context
commandsManager.runCommand('speak', { command: 'hello' }, ['DEFAULT']);
```
The `ExtensionManager` handles registering commands and creating contexts, so
@@ -152,7 +119,7 @@ It is up to the consuming application to define what contexts are possible, and
which ones are currently active. As extensions depend heavily on these, we will
likely publish guidance around creating contexts, and ways to override extension
defined contexts in the near future. If you would like to discuss potential
changes to how contexts work, please don't hesistate to createa new GitHub
changes to how contexts work, please don't hesitate to create a new GitHub
issue.
[Some additional information on Contexts can be found here.](./../index.md#contexts)
@@ -0,0 +1,30 @@
# Module: Context
- [Module: Context](#module-context)
- [Overview](#overview)
## Overview
This new module type allows you to connect components via a shared context. You can create a context that two components, e.g. a viewport and a panel can use to synchronize and communicate. An extensive example of this can be seen in the longitudinal mode’s custom extensions.
```jsx
const ExampleContext = React.createContext();
function ExampleContextProvider({ children }) {
return (
<ExampleContext.Provider value={{ example: 'value' }}>
{children}
</ExampleContext.Provider>
);
}
const getContextModule = () => [
{
name: 'ExampleContext',
context: ExampleContext,
provider: ExampleContextProvider,
},
];
```
@@ -0,0 +1,85 @@
# Module: Data Source
## Overview
The internal data structure of OHIF’s metadata follows naturalized DICOM JSON, A format pioneered by `dcmjs`. In short DICOM metadata headers with DICOM Keywords instead of tags and sequences as arrays, for easy development and clear code.
We have built a standard for fetching and mapping data into OHIF’s native format, which we call DataSources, and have provided one implementation of this standard.
You can make another datasource implementation which communicates to your backend and maps to OHIF’s native format, then use any existing mode on your platform. Your data doesn’t even need to be DICOM if you can map some proprietary data to the correct format.
The DataSource is also a place to add easy helper methods that platform-specific extensions can call in order to interact with the backend, meaning proprietary data interactions can be wrapped in extensions.
```js
const getDataSourcesModule = () => [
{
name: 'exampleDataSource',
type: 'webApi', // 'webApi' | 'local' | 'other'
createDataSource: dataSourceConfig => {
return IWebApiDataSource.create(/* */);
},
},
];
```
Default extension provides two main data sources that are commonly used: `dicomweb` and `dicomjson`
```js
import { createDicomWebApi } from './DicomWebDataSource/index.js';
import { createDicomJSONApi } from './DicomJSONDataSource/index.js';
function getDataSourcesModule() {
return [
{
name: 'dicomweb',
type: 'webApi',
createDataSource: createDicomWebApi,
},
{
name: 'dicomjson',
type: 'jsonApi',
createDataSource: createDicomJSONApi,
},
];
}
```
## Custom DataSource
You can add your custom datasource by creating the implementation using `IWebApiDataSource.create` from `@ohif/core`. This factory function creates a new "Web API" data source that fetches data over HTTP.
You need to make sure, you implement the following functions for the data source.
```js
// platform/core/src/DataSources/IWebApiDataSource.js
function create({
query,
retrieve,
store,
reject,
parseRouteParams,
retrieveSeriesMetadata,
deleteStudyMetadataPromise,
getImageIdsForDisplaySet,
getImageIdsForInstance,
}) {
/* */
}
```
You can take a look at `dicomweb` data source implementation to get an idea
`extensions/default/src/DicomWebDataSource/index.js`
## DicomMetadataStore
In `OHIF-v3` we have a central location for the metadata of studies and they are located
in `DicomMetadataStore`. Your custom datasource can communicate with `DicomMetadataStore` to store, and fetch Study/Series/Instance metadata. We will learn more about `DicomMetadataStore` in services.
@@ -0,0 +1,52 @@
Module: Hanging Protocol
## Overview
`hangingProtocolModule` provides the protocols for hanging the displaySets in the viewer.
This module can be as simple as loading a list of pre-defined protocols, or it can be more complex
and `fetch` the protocols from a server.
```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,
};
function getHangingProtocolModule() {
return [
{
name: hangingProtocolName,
protocols: [deafultProtocol],
},
];
}
```
@@ -0,0 +1,136 @@
# Module: Layout Template
- [Module: Layout Template](#module-layout-template)
- [Overview](#overview)
- [Overview Video](#overview-video)
## Overview
`LayoutTemplates` are a new concept in v3 that modes use to control the layout of a route.
A layout template is a React component that is given a set of managers that define apis to access toolbar state, commands, and hotkeys, as well as props defined by the layout template.
For instance the default LayoutTemplate takes in leftPanels, rightPanels and viewports as props, which it uses to build its view.
In addition, `layout template` has complete control over the structure of the application. You could have tools down the left side, or a strict guided workflow with tools set programmatically, the choice is yours for your use case.
```jsx
const getLayoutTemplateModule = (/* ... */) => [
{
id: 'exampleLayout',
name: 'exampleLayout',
component: ExampleLayoutComponent,
},
];
```
The `props` that are passed to `layoutTemplate` are managers and service, along with
the defined mode left/right panels, mode's defined viewports and OHIF `ViewportGridComp`.
LayoutTemplate leverages extensionManager to grab typed extension module entries:
`*.getModuleEntry(id)`
A simplified code for `Default extention`'s layout template is:
```jsx
// extensions/default/src/ViewerLayout/index.jsx
import React from 'react'
import { SidePanel } from '@ohif/ui'
function Toolbar({ servicesManager }) {
const { ToolBarService } = servicesManager.services
return (
<>
// ToolBarService.getButtonSection('primary') to get toolbarButtons
{toolbarButtons.map((toolDef, index) => {
const { id, Component, componentProps } = toolDef
return (
<Component
key={id}
id={id}
{...componentProps}
bState={buttonState}
isActive={isActive}
onInteraction={(args) => ToolBarService.recordInteraction(args)}
/>
)
})}
</>
)
}
function ViewerLayout({
// From Extension Module Params
extensionManager,
servicesManager,
hotkeysManager,
commandsManager,
// From Modes
leftPanels,
rightPanels,
viewports,
ViewportGridComp,
}) {
const getPanelData = (id) => {
const entry = extensionManager.getModuleEntry(id)
const content = entry.component
return {
iconName: entry.iconName,
iconLabel: entry.iconLabel,
label: entry.label,
name: entry.name,
content,
}
}
const getViewportComponentData = (viewportComponent) => {
const entry = extensionManager.getModuleEntry(viewportComponent.namespace)
return {
component: entry.component,
displaySetsToDisplay: viewportComponent.displaySetsToDisplay,
}
}
const leftPanelComponents = leftPanels.map(getPanelData)
const rightPanelComponents = rightPanels.map(getPanelData)
const viewportComponents = viewports.map(getViewportComponentData)
return (
<div>
<Toolbar servicesManager={servicesManager} />
<div>
{/* LEFT SIDEPANELS */}
<SidePanel
side="left"
defaultComponentOpen={leftPanelComponents[0].name}
childComponents={leftPanelComponents}
/>
{/* TOOLBAR + GRID */}
<ViewportGridComp
servicesManager={servicesManager}
viewportComponents={viewportComponents}
commandsManager={commandsManager}
/>
{/* Rigth SIDEPANELS */}
<SidePanel
side="right"
defaultComponentOpen={rightPanelComponents[0].name}
childComponents={rightPanelComponents}
/>
</div>
</div>
)
}
```
## Overview Video
<div style="padding:56.25% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/545993263?badge=0&amp;autopause=0&amp;player_id=0&amp;app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen style="position:absolute;top:0;left:0;width:100%;height:100%;" title="Viewer-layout"></iframe></div><script src="https://player.vimeo.com/api/player.js"></script>
+81 -41
View File
@@ -1,13 +1,16 @@
# Module: Panel
## Overview
UI that is intended to be displayed within a panel. The default LayoutTemplate has panels on the left and right sides, however one could make a template with panels at the top or bottom and make extensions with panels intended for such slots.
An extension can register a Panel Module by defining a `getPanelModule` method.
The panel module provides the ability to define `menuOptions` and `components`
that can be used by the consuming application. `components` are React Components
that can be displayed in the consuming application's "Panel" Component.
![Panel Extension](../../assets/img/extensions-panel.gif)
<center><i>A panel extension example</i></center>
<!-- <center><i>A panel extension example</i></center> -->
The `menuOptions`'s `target` key points to a registered `components`'s `id`. A
`defaultContext` is applied to all `menuOption`s; however, each `menuOption` can
@@ -16,46 +19,83 @@ optional provide it's own `context` value.
The `getPanelModule` receives an object containing the `ExtensionManager`'s
associated `ServicesManager` and `CommandsManager`.
![panel-module-v3](../../assets/img/panel-module-v3.png)
```js
import MyComponent from './MyComponent.js';
import PanelMeasurementTable from './PanelMeasurementTable.js';
function getPanelModule({
commandsManager,
extensionManager,
servicesManager,
}) {
const wrappedMeasurementPanel = () => {
return (
<PanelMeasurementTable
commandsManager={commandsManager}
servicesManager={servicesManager}
/>
);
};
return [
{
name: 'measure',
iconName: 'list-bullets',
iconLabel: 'Measure',
label: 'Measurements',
isDisabled: studies => {}, // optional
component: wrappedMeasurementPanel,
},
];
}
```
## Consuming Panels Inside Modes
As explained earlier, extensions make the functionalities and components available and
`modes` utilize them to build an app. So, as seen above, we are not actually defining
which side the panel should be opened. Our extension is providing the component with
its.
New: You can easily add multiple panels to the left/right side of the viewer using the mode
configuration. As seen below, the `leftPanels` and `rightPanels` accept an `Array` of
the `IDs`.
```js
export default function mode({ modeConfiguration }) {
return {
id: "viewer",
routes: [
{
path: "longitudinal",
layoutTemplate: ({ location, servicesManager }) => {
return {
id,
props: {
leftPanels: [
"org.ohif.measurement-tracking.panelModule.seriesList",
],
rightPanels: [
"org.ohif.measurement-tracking.panelModule.trackedMeasurements",
],
viewports,
},
};
},
},
],
extensions: [
"org.ohif.default",
"org.ohif.cornerstone",
"org.ohif.measurement-tracking",
"org.ohif.dicom-sr",
],
};
}
export default {
id: 'example-panel-module',
/**
* @param {object} params
* @param {ServicesManager} params.servicesManager
* @param {CommandsManager} params.commandsManager
*/
getPanelModule({ servicesManager, commandsManager }) {
return {
menuOptions: [
{
// A suggested icon
// Available icons determined by consuming app
icon: 'list',
// A suggested label
label: 'Magic',
// 'right' or 'left'
from: 'right',
// The target component to toggle open/close
target: 'target-component-id',
// UI Hint; If the target panel is in a "disabled" state
isDisabled: studies => {
return false;
},
// Overrides `defaultContext`, if specified
context: ['ACTIVE_VIEWPORT:MAGIC'],
},
],
components: [
{
id: 'target-component-id',
component: MyComponent,
},
],
defaultContext: ['ROUTE:VIEWER'],
};
},
};
```
@@ -1,8 +1,13 @@
# Module: SOP Class Handler
An extension can register a [SOP Class][sop-class-link] Handler Module by
defining a `getSopClassHandlerModule` method. The [SOP Class][sop-class-link]
Handler is a bit different from the other modules, as it doesn't provide a `1:1`
## Overview
This module defines how a specific DICOM SOP class should be processed to make a displaySet, something that can be hung in a viewport. An extension can register a [SOP Class][sop-class-link] Handler Module by defining a `getSopClassHandlerModule` method. The [SOP Class][sop-class-link].
The mode chooses what SOPClassHandlers to use, so you could process a series in a different way depending on mode within the same application.
SOPClassHandler is a bit different from the other modules, as it doesn't provide a `1:1`
schema for UI or provide it's own components. It instead defines:
- `sopClassUIDs`: an array of string SOP Class UIDs that the
@@ -14,87 +19,82 @@ A `displaySet` has the following shape:
```js
return {
plugin: 'html',
Modality: 'SR',
displaySetInstanceUID: 0,
wadoRoot: study.getData().wadoRoot,
wadoUri: instance.getData().wadouri,
SOPInstanceUID: instance.getSOPInstanceUID(),
SeriesInstanceUID: series.getSeriesInstanceUID(),
StudyInstanceUID: study.getStudyInstanceUID(),
authorizationHeaders,
};
Modality: 'MR',
displaySetInstanceUIDD
SeriesDate,
SeriesTime,
SeriesInstanceUID,
StudyInstanceUID,
SeriesNumber,
FrameRate,
SeriesDescription,
isMultiFrame,
numImageFrames,
SOPClassHandlerId,
}
```
Where the `plugin` key is used to influence the default `ViewportComponent` for
rendering the `displaySet`. Additional properties are passed to the
`ViewportComponent` and used by the default `StudyBrowser` to render
"thumbnails" for each `displaySet`
## Example SOP Class Handler Module
```js
const SOP_CLASS_UIDS = {
BASIC_TEXT_SR: '1.2.840.10008.5.1.4.1.1.88.11',
ENHANCED_SR: '1.2.840.10008.5.1.4.1.1.88.22',
import ImageSet from '@ohif/core/src/classes/ImageSet';
const sopClassDictionary = {
CTImageStorage: "1.2.840.10008.5.1.4.1.1.2",
MRImageStorage: "1.2.840.10008.5.1.4.1.1.4",
};
export default {
id: 'example-sop-class-handler-module',
/**
* @param {object} params
* @param {ServicesManager} params.servicesManager
* @param {CommandsManager} params.commandsManager
*/
getSopClassHandlerModule({ servicesManager, commandsManager }) {
return {
id: 'OHIFDicomHtmlSopClassHandler',
sopClassUIDs: Object.values(SOP_CLASS_UIDS),
// It is important to note that the used SOPClassUIDs in the modes are in the order that is specified in the array.
const sopClassUids = [
sopClassDictionary.CTImageStorage,
sopClassDictionary.MRImageStorage,
;
/**
* @param {object} series -
* @param {object} study -
* @param {object} dicomWebClient -
* @param {object} authorizationHeaders -
*/
getDisplaySetFromSeries(series, study, dicomWebClient, authorizationHeaders) {
const instance = series.getFirstInstance();
const makeDisplaySet = (instances) => {
const instance = instances[0];
const imageSet = new ImageSet(instances);
return {
plugin: 'html',
displaySetInstanceUID: 0,
wadoRoot: study.getData().wadoRoot,
wadoUri: instance.getData().wadouri,
SOPInstanceUID: instance.getSOPInstanceUID(),
SeriesInstanceUID: series.getSeriesInstanceUID(),
StudyInstanceUID: study.getStudyInstanceUID(),
authorizationHeaders,
};
imageSet.setAttributes({
displaySetInstanceUID: imageSet.uid,
SeriesDate: instance.SeriesDate,
SeriesTime: instance.SeriesTime,
SeriesInstanceUID: instance.SeriesInstanceUID,
StudyInstanceUID: instance.StudyInstanceUID,
SeriesNumber: instance.SeriesNumber,
FrameRate: instance.FrameTime,
SeriesDescription: instance.SeriesDescription,
Modality: instance.Modality,
isMultiFrame: isMultiFrame(instance),
numImageFrames: instances.length,
SOPClassHandlerId: `${id}.sopClassHandlerModule.${sopClassHandlerName}`,
});
return imageSet;
};
getSopClassHandlerModule = () => {
return [
{
name: 'stack,
sopClassUids,
getDisplaySetsFromSeries: makeDisplaySet,
},
}
];
};
```
### More examples :
- [Dicom-HTML SOP][dicom-html-sop]
- [Dicom-PDF SOP][dicom-pdf-sop]
- [Dicom-Microscopy SOP][dicom-micro-sop]
- [Dicom-Segmentation SOP][dicom-seg-sop]
You can find another example for this mapping between raw metadata and displaySet for
`DICOM-SR` extension.
## `@ohif/viewer` usage
We use the `sopClassHandlerModule`s in three different places:
- `ViewerLocalFileData.js`
- `ViewerRetrieveStudyData.js`
- `StandaloneRouting.js`
Each time, it is used to map study and series data to `displaySets`. It does
this by working alongside the `StudyMetadataManager` in `@ohif/core`. That
manager has the method `createDisplaySets` that takes an array of
`sopClassHandlerModules`.
We use the `sopClassHandlerModule`s in `DisplaySetService` where we
transform instances from the raw metadata format to a OHIF displaySet format.
You can read more about DisplaySetService here.
<!-- prettier-ignore-start -->
[sop-class-link]: http://dicom.nema.org/dicom/2013/output/chtml/part04/sect_B.5.html
+210 -83
View File
@@ -1,130 +1,257 @@
# Module: Toolbar
An extension can register a Toolbar Module by defining a `getToolbarModule`
method. This module is commonly used to define:
method. `OHIF-v3`'s `default` extension (`"ohif.org.default"`) provides 5 main toolbar button types:
- [Toolbar buttons](#button-definitions)
- [Nested toolbar menus](#nested-toolbar-menus)
- [Custom components](#custom-components)
- [Module: Toolbar](#module-toolbar)
- [Example Toolbar Module](#example-toolbar-module)
- [Toolbar buttons consumed in modes](#toolbar-buttons-consumed-in-modes)
- [Button Definitions](#button-definitions)
- [Nested Buttons](#nested-buttons)
- [Layout Template](#layout-template)
- [Custom Button](#custom-button)
- [Custom tool](#custom-tool)
![toolbarModule](../../assets/img/toolbarModule.png)
![Toolbar Extension](../../assets/img/extensions-toolbar.gif)
<center><i>Example toolbar button using the Dialog Service to show CINE controls.</i></center>
## Example Toolbar Module
The Toolbar Module should return an array of `definitions` and a
`defaultContext`. There are currently a few different variations of definitions,
The Toolbar Module should return an array of `objects`. There are currently a few different variations of definitions,
each one is detailed further down.
```js
export default {
id: 'example-toolbar-module',
export default function getToolbarModule({ commandsManager, servicesManager }) {
/**
* @param {object} params
* @param {ServicesManager} params.servicesManager
* @param {CommandsManager} params.commandsManager
*/
getToolbarModule({ servicesManager, commandsManager }) {
return {
definitions: [
/* Array of definitions */
],
defaultContext: ['ROUTE:VIEWER'],
};
},
};
return [
{
name: 'ohif.divider',
defaultComponent: ToolbarDivider,
clickHandler: () => {},
},
{
name: 'ohif.action',
defaultComponent: ToolbarButton,
clickHandler: () => {},
},
{
name: 'ohif.radioGroup',
defaultComponent: ToolbarButton,
clickHandler: () => {},
},
{
name: 'ohif.splitButton',
defaultComponent: ToolbarSplitButton,
clickHandler: () => {},
},
{
name: 'ohif.layoutSelector',
defaultComponent: ToolbarLayoutSelector,
clickHandler: (evt, clickedBtn, btnSectionName) => {},
}
]
}
```
## Toolbar buttons consumed in modes
Below we can see a simplified version of the `longitudinal` mode that shows how
a mode can add buttons to the toolbar by calling `ToolBarService.addButtons(toolbarButtons)`.
`toolbarButtons` is an array of `toolDefinitions` which we will learn next.
```js
export default function mode({ modeConfiguration }) {
return {
id: 'viewer',
displayName: 'Basic Viewer',
onModeEnter: ({ servicesManager, extensionManager }) => {
const { ToolBarService } = servicesManager.services;
ToolBarService.init(extensionManager);
ToolBarService.addButtons(toolbarButtons);
},
routes: [
{
path: 'longitudinal',
layoutTemplate: ({ location, servicesManager }) => {
return {/* */};
},
},
],
extensions: [
'org.ohif.default',
'org.ohif.cornerstone',
'org.ohif.measurement-tracking',
'org.ohif.dicom-sr',
],
};
}
```
## Button Definitions
The simplest definition has the following properties:
The simplest toolbarButtons definition has the following properties:
![toolbarModule-zoom](../../assets/img/toolbarModule-zoom.png)
```js
{
id: 'StackScroll',
label: 'Stack Scroll',
icon: 'bars',
type: 'setToolActive',
commandName: 'setToolActive',
commandOptions: { toolName: 'StackScroll' },
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 component and behavior | `"setToolActive"`, `"command"` |
| `commandName` | (optional) The command to run when the button is used. | Any command registed by a `CommandModule` |
| `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` | \* |
| `context` | (optional) Overrides module's `defaultContext` | Array of string context names |
Where a button with a `type` of `setToolActive` has an "active" styling applied
when clicked; removing the active styling from all other buttons.
## Nested Toolbar Menus
There are three main types of toolbar buttons:
You can indicate that buttons should be grouped and nested in a submenu by
including `buttons` property in a definition:
- `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
![toolbarModule-nested-buttons](../../assets/img/toolbarModule-nested-buttons.png)
```js
// modes/longitudinal/src/toolbarButtons.js
{
id: 'More',
label: 'More',
icon: 'ellipse-circle',
buttons: [
{
id: 'cstInvert',
label: 'Invert',
icon: 'circle',
type: 'command',
commandName: 'invertViewport',
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',
}
},
],
},
}
```
![Toolbar Extension](../../assets/img/extensions-toolbar-nested.gif)
<div style="padding:62.5% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/547957214?badge=0&amp;autopause=0&amp;player_id=0&amp;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>
<center><i>Example toolbar button demonstrating nested buttons.</i></center>
## Custom Components
The Toolbar Modules supports rendering custom components in place of the
application's default. In place of the `type`, `commandName`, and
`commandOptions` properties, we instead specify a `CustomComponent`.
## Layout Template
Layout selector button and logic is also provided by the OHIF-v3 `default` extension.
To use it, you can just add the following definition to the list of `toolDefinitions`
![toolbarModule-layout](../../assets/img/toolbarModule-layout.png)
```js
{
id: 'Custom',
label: 'Custom',
icon: 'custom-icon',
CustomComponent: CustomToolbarComponent,
id: 'Layout',
type: 'ohif.layoutSelector',
}
```
The `CustomComponent` components will receive the following props:
<div style="padding:56.25% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/545993263?badge=0&amp;autopause=0&amp;player_id=0&amp;app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen style="position:absolute;top:0;left:0;width:100%;height:100%;" title="Viewer-layout"></iframe></div><script src="https://player.vimeo.com/api/player.js"></script>
```html
<CustomComponent
parentContext="{parentContext}"
toolbarClickCallback="{_handleToolbarButtonClick.bind(this)}"
button="{button}"
key="{button.id}"
activeButtons="{activeButtonsIds}"
isActive="{isActive}"
/>
## Custom Button
You can also create your own extension, and add your new custom tool appearance (e.g., split horizantlly instead of vertically for split tool).
Simply add `getToolbarModule` to your extension, and pass your tool react component to its
`defaultComponent` property in the returned object.
You can use `@ohif/ui` components such as `IconButton, Icon, Tooltip, ToolbarButton` to
build your own component.
```js
import myToolComponent from './myToolComponent'
export default function getToolbarModule({ commandsManager, servicesManager }) {
return [
{
name: 'new-tool-type',
defaultComponent: myToolComponent,
clickHandler: () => {},
},
]
}
```
| Property | Type | Description |
| ---------------------- | -------- | ------------------------------- |
| `activeButtons` | string[] | list of active buttons |
| `button` | object | its own definition object |
| `key` | string | React key prop |
| `isActive` | boolean | If current button is active |
| `parentContext` | ? | The parent component's context? |
| `toolbarClickCallback` | func | Callback method for clicks |
## Custom tool
<mark> I want to create a new tool
+70 -21
View File
@@ -1,46 +1,95 @@
# Module: Viewport
An extension can register a Viewport Module by defining a `getViewportModule`
## Overview
Viewports consume a displaySet and display/allow the user to interact with data. An extension can register a Viewport Module by defining a `getViewportModule`
method that returns a React component. Currently, we use viewport components to
add support for:
- 2D Medical Image Viewing (cornerstone ext.)
- Structured Reports as HTML (dicom html ext.)
- Encapsulated PDFs as PDFs (dicom pdf ext.)
- Structured Reports as SR (DICOM SR ext.)
- Structured Reports as HTML (DICOM html ext.)
- Encapsulated PDFs as PDFs (DICOM pdf ext.)
- Whole Slide Microscopy Viewing (whole slide ext.)
- etc.
The general pattern is, the [`sopClassHandlerModule`](#) helps us determine
which Viewport Component a set of `sopClassUIDs` should default to. The Viewport
Component receives props containing a display set it should know how to render.
## Viewport Component Props
Each `ViewportComponent` will receive the following props:
The general pattern is that a mode can define which `Viewport` to use for which specific
`SOPClassHandlerUID`, so if you want to fork just a single Viewport component for a specialized mode, this is possible.
```html
<viewportComponent
viewportData="{viewportData}"
viewportIndex="{viewportIndex}"
children="{[children]}"
/>
```JSX
// displaySet, viewportIndex, dataSource
const getViewportModule = () => {
const wrappedViewport = props => {
return (
<ExampleViewport
{...props}
onEvent={data => {
commandsManager.runCommand('commandName', data);
}}
/>
);
};
return [{ name: 'example', component: wrappedViewport }];
};
```
| Property | Type | Description |
| --------------- | --------------- | --------------------------------- |
| `children` | React.element[] | |
| `viewportData` | object | `viewportSpecificData` (probably) |
| `viewportIndex` | number | |
## Example Viewport Component
A simplified version of the tracked CornerstoneViewport is shown below, which creates
a cornerstone viewport and and action bar on top of it.
```JSX
function TrackedCornerstoneViewport({
children,
dataSource,
displaySet,
viewportIndex,
servicesManager,
extensionManager,
commandsManager,
}) {
const renderViewport = () => {
const { component: Component } = extensionManager.getModuleEntry(
'org.ohif.cornerstone.viewportModule.cornerstone'
)
return (
<Component
onElementEnabled={onElementEnabled}
element={element}
{...props}
></Component>
)
}
return (
<>
<ViewportActionBar onDoubleClick onSeriesChange />
<div className="relative flex flex-row w-full h-full overflow-hidden">
{renderViewport()}
</div>
</>
)
}
```
![viewportModule](../../assets/img/viewportModule.png)
### `@ohif/viewer`
Viewport components are managed by the `ViewportGrid` Component. Which Viewport
component is used depends on:
- Hanging Protocols
- The Layout Configuration
- Registered SopClassHandlers
- The SopClassUID for visible/selected datasets
![Cornerstone Viewport](../../assets/img/extensions-viewport.png)
![viewportModule-layout](../../assets/img/viewportModule-layout.png)
<center><i>An example of three cornerstone Viewports</i></center>