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

@@ -7,6 +7,19 @@
</tr>
</thead>
<tbody>
<!-- CORNERSTONE.js -->
<tr>
<td>
<a href="">
Default
</a>
</td>
<td>
Default extension provides default viewer layout, a study/series
browser, and a datasource that maps to a DICOMWeb compliant backend
</td>
<td>commandsModule, ContextModule, DataSourceModule, HangingProtocolModule, LayoutTemplateModule, PanelModule, SOPClassHandlerModule, ToolbarModule</td>
</tr>
<!-- CORNERSTONE.js -->
<tr>
<td>
@@ -15,34 +28,12 @@
</a>
</td>
<td>
A viewport powered by <code>cornerstone.js</code>. Adds support for 2D DICOM rendering and manipulation, as well as support for the tools features in <a href="https://tools.cornerstonejs.org/examples/"><code>cornerstone-tools</code></a>. Also adds "CINE Dialog" to the Toolbar.
Provides rendering functionalities for 2D images.
</td>
<td>Viewport, Toolbar</td>
</tr>
<!-- VTK.js -->
<tr>
<td>
<a href="https://www.npmjs.com/package/@ohif/extension-vtk">
VTK.js
</a>
</td>
<td>
A viewport powered by <code>vtk.js</code>. Adds support for volume renderings and advanced features like MPR. Also adds "3D Rotate" to the Toolbar.
</td>
<td>Viewport, Toolbar</td>
</tr>
<!-- dicom-html -->
<tr>
<td>
<a href="https://www.npmjs.com/package/@ohif/extension-dicom-html">DICOM HTML</a>
</td>
<td>
Renders text and HTML content for <a href="https://github.com/OHIF/Viewers/blob/master/extensions/dicom-html/src/OHIFDicomHtmlSopClassHandler.js#L4-L12">specific SopClassUIDs</a>.
</td>
<td>Viewport, SopClassHandler</td>
<td>ViewportModule, CommandsModule</td>
</tr>
<!-- dicom-pdf -->
<tr>
<!-- <tr>
<td>
<a href="https://www.npmjs.com/package/@ohif/extension-dicom-pdf">DICOM PDF</a>
</td>
@@ -50,26 +41,27 @@
Renders PDFs for a <a href="https://github.com/OHIF/Viewers/blob/master/extensions/dicom-pdf/src/OHIFDicomPDFSopClassHandler.js#L4-L6">specific SopClassUID</a>.
</td>
<td>Viewport, SopClassHandler</td>
</tr>
<!-- dicom-microscopy -->
</tr> -->
<!-- dicom-sr -->
<tr>
<td>
<a href="https://www.npmjs.com/package/@ohif/extension-dicom-microscopy">DICOM Microscopy</a>
<a href="">DICOM SR</a>
</td>
<td>
Renders Microscopy images for a <a href="https://github.com/OHIF/Viewers/blob/master/extensions/dicom-microscopy/src/DicomMicroscopySopClassHandler.js#L5-L7">specific SopClassUID</a>.
Maintained extensions for cornerstone and visualization of DICOM Structured Reports
</td>
<td>Viewport, SopClassHandler</td>
<td>ViewportModule, CommandsModule, SOPClassHandlerModule</td>
</tr>
<!-- dicom-segmentation -->
<!-- Measurement-tracking -->
<tr>
<td>
<a href="https://www.npmjs.com/package/@ohif/extension-dicom-segmentation">DICOM Segmentation</a>
<a href="">Measurement tracking</a>
</td>
<td>
Renders segmentation images for a <a href="https://github.com/OHIF/Viewers/blob/master/extensions/dicom-segmentation/src/OHIFDicomSegSopClassHandler.js#L5-L7">specific SopClassUID</a>.
Tracking measurements in the measurement panel
</td>
<td>Panel, Toolbar</td>
<td> ContextModule,PanelModule,ViewportModule,CommandsModule</td>
</tr>
</tbody>
</table>
+94
View File
@@ -0,0 +1,94 @@
<table>
<thead>
<tr>
<th align="left" width="30%">
Types
</th>
<th align="left">Description</th>
<th align="left">Examples</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">
<a href="./modules/layout-template.md">
LayoutTemplate (NEW)
</a>
</td>
<td align="left">Control Layout of a route</td>
<td align="left"></td>
</tr>
<tr>
<td align="left">
<a href="./modules/data-source.md">
DataSource (NEW)
</a>
</td>
<td align="left">Control the mapping from DICOM metadata to OHIF-metadata</td>
<td align="left"></td>
</tr>
<tr>
<td align="left">
<a href="./modules/sop-class-handler.md">
SOPClassHandler
</a>
</td>
<td align="left">Determines how retrieved study data is split into "DisplaySets"</td>
<td align="left"></td>
</tr>
<tr>
<td align="left">
<a href="./modules/panel.md">
Panel
</a>
</td>
<td align="left">Adds left or right hand side panels</td>
<td align="left"></td>
</tr>
<tr>
<td align="left">
<a href="./modules/viewport.md">
Viewport
</a>
</td>
<td align="left">Adds a component responsible for rendering a "DisplaySet"</td>
<td align="left"></td>
</tr>
<tr>
<td align="left">
<a href="./modules/commands.md">
Commands
</a>
</td>
<td align="left">Adds named commands, scoped to a context, to the CommandsManager</td>
<td align="left"></td>
</tr>
<tr>
<td align="left">
<a href="./modules/toolbar.md">
Toolbar
</a>
</td>
<td align="left">Adds buttons or custom components to the toolbar</td>
<td align="left"></td>
</tr>
<tr>
<td align="left">
<a href="./modules/context.md">
Context
</a>
</td>
<td align="left">Shared state for a workflow or set of extension module definitions</td>
<td align="left"></td>
</tr>
<tr>
<td align="left">
<a href="./modules/hpModule.md">
HangingProtocol
</a>
</td>
<td align="left">Adds hanging protocol rules</td>
<td align="left"></td>
</tr>
</tbody>
</table>
+119 -96
View File
@@ -1,53 +1,50 @@
# Extensions
- [Overview](#overview)
- [Concepts](#concepts)
- [Extensions](#extensions)
- [Overview](#overview)
- [Extension Skeleton](#extension-skeleton)
- [OHIF-Maintained Extensions](#ohif-maintained-extensions)
- [Registering an Extension](#registering-an-extension)
- [Lifecylce Hooks](#lifecycle-hooks)
- [Registering at Runtime](#registering-at-runtime)
- [Registering at Build Time](#registering-at-build-time)
- [Lifecycle Hooks](#lifecycle-hooks)
- [Modules](#modules)
- [Contexts](#contexts)
- [Consuming Extensions](#consuming-extensions)
- [Extension Manager](#extensionmanager)
- [Maintained Extensions](#maintained-extensions)
- [Contexts](#contexts)
## Overview
We have re-designed the architecture of the `OHIF-v3` to enable building applications
that are easily extensible to various use cases (modes) that behind the scene would utilize desired functionalities (extensions) to reach the goal of the use case.
We use extensions to help us isolate and package groups of related features.
Extensions provide functionality, ui components, and new behaviors. Ideally,
they're built in a way that allows them to extend entirely different
implementations of the `@ohif/viewer` project.
Previously, extensions were “additive” and could not easily be mixed and matched within the same viewer for different use cases. Previous `OHIF-v2` architecture meant that
any minor extension alteration usually would require the user to hard fork. E.g. removing some of the tools from the toolbar of the cornerstone extension meant you had to hard fork it, which was frustrating if the implementation was otherwise the same as master.
> - Developers should make packages of *reusable* functionality as extensions, and can consume
> publicly available extensions.
> - Any conceivable radiological workflow or viewer setup will be able to be built with the platform through *modes*.
Practical examples of extensions include:
- A set of segmentation tools that build on top of the `cornerstone` viewport
- A set of rendering functionalities to volume render the data
- [See our maintained extensions for more examples of what's possible](#maintained-extensions)
<mark>Diagram showing how extensions are configured and accessed.
<!--
<div style="text-align: center;">
<a href="/assets/img/extensions-diagram.png">
<img src="/assets/img/extensions-diagram.png" alt="Extensions Diagram" style="margin: 0 auto; max-width: 500px;" />
</a>
<div><i>Diagram showing how extensions are configured and accessed.</i></div>
</div>
</div> -->
The `@ohif/viewer`'s application level configuration gives us the ability to add
and configure extensions. When the application starts, extensions are registered
with the `ExtensionManager`. Different portions of the `@ohif/viewer` project
will use registered extensions to influence application behavior.
Extensions allow us to:
- Wrap and integrate functionality of 3rd party dependencies in a reusable way
- Change how application data is mapped and transformed
- Display a consistent/cohesive UI
- Inject custom components to override built-in components
Practical examples of extensions include:
- A set of segmentation tools that build on top of the `cornerstone` viewport
- Showing ML/AI report summaries for the selected study/series/image
- Support for parsing DICOM structured reports and displaying them in a user
friendly way
- [See our maintained extensions for more examples of what's possible](#maintained-extensions)
## Concepts
### Extension Skeleton
## Extension Skeleton
An extension is a plain JavaScript object that has an `id` property, and one or
more [modules](#modules) and/or [lifecycle hooks](#lifecycle-hooks).
@@ -62,45 +59,77 @@ export default {
// Lifecyle
preRegistration() { /* */ },
onModeEnter() { /* */ },
onModeExit() { /* */ },
// Modules
getCommandsModule() { /* */ },
getToolbarModule() { /* */ },
getLayoutTemplateModule() { /* */ },
getDataSourcesModule() { /* */ },
getSopClassHandlerModule() { /* */ },
getPanelModule() { /* */ },
getSopClassHandler() { /* */ },
getViewportModule() { /* */ },
getCommandsModule() { /* */ },
getContextModule() { /* */ },
getToolbarModule() { /* */ },
getHangingProtocolModule() { /* */ },
}
```
### Registering an Extension
## OHIF-Maintained Extensions
A small number of powerful extensions for popular use cases are maintained by
OHIF. They're co-located in the [`OHIF/Viewers`][viewers-repo] repository, in
the top level [`extensions/`][ext-source] directory.
There are two different ways to register and configure extensions: At
{% include "./_maintained-extensions-table.md" %}
## Registering an Extension
Extensions are building blocks that need to be registered. There are two different ways to register and configure extensions: At
[runtime](#registering-at-runtime) and at
[build time](#registering-at-build-time).
You can leverage one or both strategies. Which one(s) you choose depend on your
application's requirements. Each [module](#modules) defined by the extension
becomes available to the core application via the `ExtensionManager`.
application's requirements.
#### Registering at Runtime
Each [module](#modules) defined by the extension
becomes available to the modes via the `ExtensionManager` by requesting it via
its id. [Read more about Extension Manager](#extension-manager)
### Registering at Runtime
The `@ohif/viewer` uses a [configuration file](../viewer/configuration.md) at
startup. The schema for that file includes an `Extensions` key that supports an
startup. The schema for that file includes an `extensions` key that supports an
array of extensions to register.
```js
import MyFirstExtension from '@ohif/extension-first'
import MySecondExtension from '@ohif/extension-second'
const extensionConfig = {/* extension configuration */}
// prettier-ignore
const config = {
routerBasename: '/',
extensions: [
MyFirstExtension,
[
MySecondExtension,
{ /* MySecondExtensions Configuration */ },
extensionConfig
],
];
],
modes: [/* modes */],
showStudyList: true,
dataSources: [ /* data source config */]
}
```
#### Registering at Build Time
Then, behind the scene, the runtime-added extensions will get merged with the
default app extensions (note: default app extensions include: `OHIFDefaultExtension`,
`OHIFCornerstoneExtension`, `OHIFDICOMSRExtension`,
`OHIFMeasurementTrackingExtension`)
### Registering at Build Time
The `@ohif/viewer` works best when built as a "Progressive Web Application"
(PWA). If you know the extensions your application will need, you can specify
@@ -114,38 +143,63 @@ You can update the list of bundled extensions by:
1. Having your `@ohif/viewer` project depend on the extension
2. Importing and adding it to the list of extensions in the
`<repo-root>/platform/src/index.js` entrypoint.
`<repo-root>/platform/src/index.js` entrypoint:
```js
import OHIFDefaultExtension from '@ohif/extension-default';
import OHIFCornerstoneExtension from '@ohif/extension-cornerstone';
import OHIFMeasurementTrackingExtension from '@ohif/extension-measurement-tracking';
import OHIFDICOMSRExtension from '@ohif/extension-dicom-sr';
import MyFirstExtension from '@ohif/extension-first'
/** Combine our appConfiguration and "baked-in" extensions */
const appProps = {
config: window ? window.config : {},
defaultExtensions: [
OHIFDefaultExtension,
OHIFCornerstoneExtension,
OHIFMeasurementTrackingExtension,
OHIFDICOMSRExtension,
MyFirstExtension
],
};
```
## Lifecycle Hooks
Currently, there are three lifecycle hook for extensions:
### Lifecycle Hooks
Currently, there is only a single lifecycle hook for extensions:
[`preRegistration`](./lifecycle/pre-registration.md)
If an extension defines the [`preRegistration`](./lifecycle/pre-registration.md)
This hook is called once on initialization of the entire viewer application, used to initialize the extensions state, and consume user defined extension configuration. If an extension defines the [`preRegistration`](./lifecycle/pre-registration.md)
lifecycle hook, it is called before any modules are registered in the
`ExtensionManager`. It's most commonly used to wire up extensions to
[services](./../services/index.md) and [commands](./modules/commands.md), and to
bootstrap 3rd party libraries.
### Modules
Modules are the meat of extensions. They provide "definitions", components, and
filtering/mapping logic that are then made available by various managers and
services.
[`onModeEnter`](./lifecycle/on-mode-enter.md): This hook is called whenever a new mode is entered, or a mode’s data or datasource is switched. This hook can be used to initialize data.
[`onModeExit`](./lifecycle/on-mode-exit.md): Similarly to onModeEnter, this hook is called when navigating away from a mode, or before a mode’s data or datasource is changed. This can be used to clean up data (e.g. remove annotations that do not need to be persisted)
## Modules
Modules are the meat of extensions, the `blocks` that we have been talking about a lot.
They provide "definitions", components, and filtering/mapping logic that are then made available to modes and services.
Each module type has a special purpose, and is consumed by our viewer
differently.
| Type | Description | Examples |
| ------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
| [Commands](./modules/commands.md) | Adds named commands, scoped to a context, to the CommandsManager | `setToolActive()`, `nextSeries()` |
| [Panel](./modules/panel.md) | Adds left or right hand side panels | `<ThumbnailList />`, `<MeasurementsTable />` |
| [SOPClassHandler](./modules/sop-class-handler.md) | Determines how retrieved study data is split into "DisplaySets" | `getDisplaySetFromSeries()` |
| [Toolbar](./modules/toolbar.md) | Adds buttons or custom components to the toolbar | Toolbar button, nested buttons, custom |
| [Viewport](./modules/viewport.md) | Adds a component responsible for rendering a "DisplaySet" | `<CornerstoneViewport />`, `<DicomPdfViewport />` |
{% include "./_modules.md" %}
<figure style="text-align: center; font-style: italic;">Tbl. Module types with abridged descriptions and examples. Each module links to a dedicated documentation page.</figure>
### Contexts
The `@ohif/viewer` tracks "active contexts" that extensions can use to scope
@@ -163,6 +217,8 @@ module that supports this behavior can add a command with the same name, scoped
to the appropriate context. When the `command` is fired, the "active contexts"
are used to determine the appropriate implementation of the rotate behavior.
<!-- <mark>do we want the followings?
## Consuming Extensions
We consume extensions, via the `ExtensionManager`, in our `@ohif/viewer`
@@ -189,45 +245,12 @@ applications requiring a high degree of customization that can't be achieved
with current theming, configuration, extension, and services support.
If you're not sure how to achieve your goals with the extensibility available
today, create a GitHub issue!
today, create a GitHub issue! -->
### `ExtensionManager`
The `ExtensionManager` is a class made available to us via the `@ohif/core`
project (platform/core). Our application instantiates a single instance of it,
and provides a `ServicesManager` and `CommandsManager` along with the
application's configuration through the appConfig key (optional).
```js
const commandsManager = new CommandsManager();
const servicesManager = new ServicesManager();
const extensionManager = new ExtensionManager({
commandsManager,
servicesManager,
appConfig,
});
```
The `ExtensionManager` only has a few public members:
- `registerExtension` - Registers a single extension
- `registerExtensions` - Registers an array of extensions
- `modules` - An object containing registered extensions by `MODULE_TYPE`
During registration, lifecycle hooks and modules have access to the extension's
config, the application's config and `ExtensionManager`'s `ServicesManager` and
`CommandsManager` instances.
Our `@ohif/viewer` uses the `modules` member to access registered extensions at
appropriate places in our application.
## Maintained Extensions
A small number of powerful extensions for popular use cases are maintained by
OHIF. They're co-located in the [`OHIF/Viewers`][viewers-repo] repository, in
the top level [`extensions/`][ext-source] directory.
{% include "./_maintained-extensions-table.md" %}
<!--
LINKS
@@ -0,0 +1,29 @@
# Lifecycle Hook: onModeEnter
If an extension defines the `onModeEnter` lifecycle hook, it is called
when a new mode is enters, or a mode's data or datasource is switched.
For instance, in DICOM structured report extension (`dicom-sr`), we are using
`onModeEnter` to re-create the displaySets after a new mode is entered.
_Example `onModeEnter` hook implementation_
```js
export default {
id: 'org.ohif.dicom-sr',
onModeEnter({ servicesManager}) {
const { DisplaySetService } = servicesManager.services;
const displaySetCache = DisplaySetService.getDisplaySetCache();
const srDisplaySets = displaySetCache.filter(
ds => ds.SOPClassHandlerId === SOPClassHandlerId
);
srDisplaySets.forEach(ds => {
// New mode route, allow SRs to be hydrated again
ds.isHydrated = false;
});
},
};
```
@@ -0,0 +1,17 @@
# Lifecylce Hook: onModeExit
If an extension defines the `onModeExit` lifecycle hook, it is called when navigating
away from a mode. This hook can be used to clean up data tasks such as unregistering services,
removing annotations that do not need to be persisted.
_Example `onModeExit` hook implementation_
```js
export default {
id: 'myExampleExtension',
onModeExit({ servicesManager, commandsManager}) {
myCacheServie.purge()
},
};
```
@@ -13,9 +13,30 @@ The `preRegistration` hook receives an object containing the
`ExtensionManager`'s associated `ServicesManager`, `CommandsManager`, and any
`configuration` that was provided with the extension at time of registration.
_Example `preRegistration` hook implementation_
Example `preRegistration` implementation that register a new service and make it
available in the app. We will talk more in details for creating a new service for
`OHIF-v3`.
```js
// new service inside new extension
import MyNewService from './MyNewService';
export default function MyNewServiceWithServices(serviceManager) {
return {
name: 'MyNewService',
create: ({ configuration = {} }) => {
return new MyNewService(serviceManager);
},
};
}
```
and
```js
import MyNewService from './MyNewService'
export default {
id: 'MyExampleExtension',
@@ -35,6 +56,10 @@ export default {
console.log('Important stuff has been wired.');
window.importantStuff();
// Registering new services
servicesManager.registerService(MyNewService(servicesManager));
},
},
};
```
+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>