TrizTech/ohif-viewer
15
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #872 from dannyrb/docs/monorepo-updates-3

Browse Source 
docs: building, contributing, local package dev
This commit is contained in:
Danny Brown 2019-09-05 21:29:54 -04:00 committed by GitHub
commit d03d9e9a09
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 162 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.webpack/webpack.commonjs.js
View File

@ -1,3 +1,4 @@
const merge = require('webpack-merge');
const webpackBase = require('./webpack.base.js');
const cssToJavaScriptRule = require('./rules/cssToJavaScript.js');
const stylusToJavaScriptRule = require('./rules/stylusToJavaScript.js');

118
docs/latest/advanced/architecture.md
View File

@ -12,28 +12,48 @@ architected, and the role each of it's dependent libraries plays.
## Overview
The [`OHIF/Viewers`][viewers-project] project contains the source code for the
OHIF Medical Imaging Viewer. It is effectively a React [progressive web
app][pwa] (PWA) that combines the business logic housed in
[`OHIF/ohif-core`][core] and the components in our React Component library
[`OHIF/react-viewerbase`][component-library]. It provides customization for
common use cases through [configuration][configuration] and for adding
functionality via [extensions][extensions].
The [OHIF Medical Image Viewing Platform][viewers-project] is maintained as a
[`monorepo`][monorepo]. This means that this repository, instead of containing a
single project, contains many projects. If you explore our project structure,
you'll see the following:
```bash
.
├── extensions
│ ├── _example # Skeleton of example extension
│ ├── cornerstone # 2D images w/ Cornerstone.js
│ ├── dicom-html # Structured Reports as HTML in viewport
│ ├── dicom-microscopy # Whole slide microscopy viewing
│ ├── dicom-pdf # View DICOM wrapped PDFs in viewport
│ └── vtk # MPR and Volume support w/ VTK.js
│
├── platform
│ ├── core # Business Logic
│ ├── i18n # Internationalization Support
│ ├── ui # React component library
│ └── viewer # Connects platform and extension projects
│
├── ... # misc. shared configuration
├── lerna.json # MonoRepo (Lerna) settings
├── package.json # Shared devDependencies and commands
└── README.md
```
Continue reading to see how these libraries work together to create the OHIF
Viewer.
### Business Logic
Our goal is to maintain the majority of our business logic in
[`OHIF/ohif-core`](https://github.com/OHIF/ohif-core). `ohif-core` offers
pre-packaged solutions for features common to Web-based medical imaging viewers.
For example:
The [`@ohif/core`][core-github] project offers pre-packaged solutions for
features common to Web-based medical imaging viewers. For example:
- Hotkeys
- DICOM Web
- DICOM Web requests
- Hanging Protocols
- Managing a study's measurements
- Managing a study's DICOM metadata
- A flexible pattern for extensions
- [And many others](https://github.com/OHIF/ohif-core/blob/master/src/index.js#L49-L69)
- And many others
It does this while remaining decoupled from any particular view library or
rendering logic. While we use it to power our React Viewer, it can be used with
@ -41,20 +61,42 @@ Vue, React, Vanilla JS, or any number of other frameworks.
### React Component Library
[`OHIF/react-viewerbase`](https://github.com/OHIF/react-viewerbase) is a React
Component library that contains the reusable components that power the OHIF
Viewer. It allows us to build, compose, and test components in isolation; easing
the development process by reducing the need to stand-up a local PACS with test
case data.
[`@ohif/ui`][ui-github] is a React Component library that contains the reusable
components that power the OHIF Viewer. It allows us to build, compose, and test
components in isolation; easing the development process by reducing the need to
stand-up a local PACS with test case data.
Extension authors can also use these same components when building their
extension's UI; allowing for a consistent look and feel with the rest of the
application.
[Check out our component library!](https://react.ohif.org/)
### Misc. Extensions
### Internationalization (i18n)
Want to add custom logic or UI Components to the OHIF Viewer, but don't want to
maintain a fork? We expose common integration points via
[extensions](./extensions.md) to make that possible. For a list of extensions
maintained by OHIF,
...
### The Viewer
...
### Extensions & Configuration
While OHIF maintains several high value and commonly requested features in its
own extensions, there are many instances where one may wish to further extend
the viewer. Some common use cases include:
- Adding AI/ML tools and insights
- Custom workflows for guided diagnosis
- Collecting specific annotations for training data or reports
- Authentication and granular permissions
- Teleconsultation workflow, image comments, and tracking
- Adding surgical templating tools and reports
- and many others
We expose common integration points via [extensions](./extensions.md) to make
this possible. The viewer and many of our own extensions also offer
[configuration][configuration]. For a list of extensions maintained by OHIF,
[check out this helpful table](./extensions.html#ohif-maintained-extensions).
If you find yourself thinking "I wish the Viewer could do X", and you can't
@ -67,15 +109,14 @@ looking for ways to improve our extensibility ^\_^
This diagram is a conceptual illustration of how the Viewer is architected.
1. (optional) `extensions` can be registered with `ohif-core`'s extension
1. (optional) `extensions` can be registered with `@ohif/core`'s extension
manager
2. `ohif-core` provides bussiness logic and a way for `viewer` to access
2. `@ohif/core` provides bussiness logic and a way for `@ohif/viewer` to access
registered extensions
3. The `viewer` composes and provides data to components from our component
library (`react-viewerbase`)
4. The `viewer` can be built and served as a stand-alone PWA, or as an
embeddable package
([`ohif-viewer`](https://www.npmjs.com/package/ohif-viewer))
3. The `@ohif/viewer` composes and provides data to components from our
component library (`@ohif/ui`)
4. The `@ohif/viewer` can be built and served as a stand-alone PWA, or as an
embeddable package ([`@ohif/viewer`][viewer-npm])
![Architecture Diagram](../assets/img/architecture-diagram.png)
@ -83,17 +124,17 @@ This diagram is a conceptual illustration of how the Viewer is architected.
## Common Questions
> When should I use the packaged source `ohif-viewer` versus building a PWA from
> the source?
> When should I use the packaged source `@ohif/viewer` versus building a PWA
> from the source?
...
> Can I create my own Viewer using Vue.js or Angular.js?
You can, but you will not be able to leverage as much of the existing code and
components. `ohif-core` could still be used for business logic, and to provide a
model for extensions. `react-viewerbase` would then become a guide for the
components you would need to recreate.
components. `@ohif/core` could still be used for business logic, and to provide
a model for extensions. `@ohif/ui` would then become a guide for the components
you would need to recreate.
<!--
Links
@ -101,9 +142,10 @@ components you would need to recreate.
<!-- prettier-ignore-start -->
[viewers-project]: https://github.com/OHIF/Viewers
[viewer-npm]: https://www.npmjs.com/package/@ohif/viewer
[pwa]: https://developers.google.com/web/progressive-web-apps/
[core]: https://github.com/OHIF/ohif-core
[component-library]: https://github.com/OHIF/react-viewerbase
[configuration]: ../essentials/configuration.md
[extensions]: ./extensions.m
[extensions]: ./extensions.md
[core-github]: https://github.com/OHIF/viewers/platform/core
[ui-github]: https://github.com/OHIF/Viewers/platform/ui
<!-- prettier-ignore-end -->

13
docs/latest/deployment/index.md
View File

@ -1,11 +1,11 @@
# Deployment
The OHIF Viewer can be embedded in other web applications via it's [packaged
script source][ohif-viewer-npm], or served up as a stand-alone PWA ([progressive
web application][pwa-url]) by building and hosting a collection of static
assets. In either case, you will need to configure your instance of the Viewer
so that it can connect to your data source (the database or PACS that provides
the data your Viewer will display).
script source][viewer-npm], or served up as a stand-alone PWA ([progressive web
application][pwa-url]) by building and hosting a collection of static assets. In
either case, you will need to configure your instance of the Viewer so that it
can connect to your data source (the database or PACS that provides the data
your Viewer will display).
## Overview
@ -196,8 +196,7 @@ Please feel free to suggest or contribute your own recipes.
-->
<!-- prettier-ignore-start -->
[ohif-viewer-npm]: https://www.npmjs.com/package/ohif-viewer
[viewer-npm]: https://www.npmjs.com/package/@ohif/viewer
[pwa-url]: https://developers.google.com/web/progressive-web-apps/
[static-assets-url]: https://www.maxcdn.com/one/visual-glossary/static-content/
[app-store]: https://medium.freecodecamp.org/i-built-a-pwa-and-published-it-in-3-app-stores-heres-what-i-learned-7cb3f56daf9b

33
docs/latest/deployment/recipes/embedded-viewer.md
View File

@ -12,13 +12,8 @@ include tags. Here's how it works:
<ul>
<li>
<a href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css">
<code>bootstrap@3.3.7</code>
</a>
</li>
<li>
<a href="https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700|Sanchez&display=swap">
<code>Google Fonts, Sanchez & Roboto</code>
<a href="https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700&display=swap">
<code>Google Font: Roboto</code>
</a>
</li>
<li>
@ -32,15 +27,13 @@ include tags. Here's how it works:
</a>
</li>
<li>
<a href="https://unpkg.com/ohif-viewer/dist/index.umd.js">
<code>ohif-viewer@latest</code>
<a href="https://unpkg.com/@ohif/viewer">
<code>@ohif/viewer@latest</code>
</a>
</li>
</ul>
<ol start="2">
<li>The <a href="">WADO Image Loader Codecs and Web Worker source code</a>
should be accessible from your server's root</li>
<li>Create a JS Object to hold the OHIF Viewer's configuration. Here are some
example values that would allow the viewer to hit our public PACS:</li>
</ol>
@ -74,7 +67,7 @@ window.config = {
</li></ol>
```js
// Made available by the `ohif-viewer` script included in step 1
// Made available by the `@ohif/viewer` script included in step 1
var Viewer = window.OHIFStandaloneViewer.App;
var app = React.createElement(Viewer, window.config, null);
@ -89,16 +82,20 @@ First, check out this fully functional [CodeSandbox][code-sandbox] example. If
you're still having trouble, feel free to search or GitHub issues. Can't find
anything related your problem? Create a new one.
> When I include bootstrap, other styles on my page no longer work correctly.
> What can I do?
> My application's styles are impacting the OHIF Viewer's look and feel. What
> can I do?
When we include `bootsrap` (and the other dependencies), they are added
globally. This has the potential of causing conflicts with other scripts and
styles on the page. To prevent this, `embed` the viewer in a new/empty web page.
Have that working? Good. Now `embed` that new page using an
When you include stylesheets and scripts, they are added globally. This has the
potential of causing conflicts with other scripts and styles on the page. To
prevent this, `embed` the viewer in a new/empty web page. Have that working?
Good. Now `embed` that new page using an
[`<iframe>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe).
This should produce the expected result while also protecting your page from any
globally defined styles/scripts.
<!--
LINKS
-->
[code-sandbox]: https://codesandbox.io/s/ohif-viewer-script-tag-usage-b3st9

65
docs/latest/essentials/configuration.md
View File

@ -4,22 +4,47 @@
> one up, check out the [`Data Source` Guide](./data-source.md) or a deployment
> recipe that contains an open source Image Archive
## How it Works
## Overview
The configuration for our project is in the `/public/config` directory. Our
build process knows which configuration file to use based on the `APP_CONFIG`
environment variable. By default, its value is
[`default.js`](https://github.com/OHIF/Viewers/blob/master/platform/viewer/public/config/default.js).
When we build, the `%APP_CONFIG%` value in
our[`/public/index.html`](https://github.com/OHIF/Viewers/blob/master/platform/viewer/public/index.html)
file is substituted for the correct configuration file's name. This sets the
`window.config` equal to our configuration file's value.
### Configuration Files
The configuration for our viewer is in the `<root>platform/viewer/public/config`
directory. Our build process knows which configuration file to use based on the
`APP_CONFIG` environment variable. By default, its value is
[`config/default.js`][default-config]. The majority of the viewer's features,
and registered extension's features, are configured using this file.
**Embedded Use Note:**
Alternatively, when using the `commonjs` bundle for embedded use cases, these
same values are what you'll pass to `installViewer` method:
`OHIFStandaloneViewer.installViewer(window.config)`
### Environment Variables
We use environment variables at build and dev time to change the Viewer's
behavior. We can update the `HTML_TEMPLATE` to easily change which extensions
are registered, and specify a different `APP_CONFIG` to connect to an
alternative data source (or even specify different default hotkeys).
| Environment Variable | Description | Default |
| -------------------- | -------------------------------------------------------------------------------------------------- | ------------------- |
| `HTML_TEMPLATE` | Which [HTML template][html-templates] to use as our web app's entry point. Specific to PWA builds. | `index.html` |
| `PUBLIC_URL` | The route relative to the host that the app will be served from. Specific to PWA builds. | `/` |
| `APP_CONFIG` | Which [configuration file][config-file] to copy to output as `app-config.js` | `config/default.js` |
| `PROXY_TARGET` | When developing, proxy requests that match this pattern to `PROXY_DOMAIN` | `undefined` |
| `PROXY_DOMAIN` | When developing, proxy requests from `PROXY_TARGET` to `PROXY_DOMAIN` | `undefined` |
### Registering Extensions
> :warn: Instructions coming soon
## How do I configure my project?
The simplest way is to update the existing default config:
_/public/config/default.js_
_/platform/viewer/public/config/default.js_
```js
window.config = {
@ -47,10 +72,24 @@ You can also create a new config file and specify its path relative to the build
output's root by setting the `APP_CONFIG` environment variable. You can set the
value of this environment variable a few different ways:
- [Add a temporary environment variable in your shell](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-temporary-environment-variables-in-your-shell)
- [Add environment specific variables in `.env` file(s)](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-development-environment-variables-in-env)
- ~[Add a temporary environment variable in your shell](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-temporary-environment-variables-in-your-shell)~
- Previous `react-scripts` functionality that we need to duplicate with
`dotenv-webpack`
- ~[Add environment specific variables in `.env` file(s)](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-development-environment-variables-in-env)~
- Previous `react-scripts` functionality that we need to duplicate with
`dotenv-webpack`
- Using the `cross-env` package in an npm script:
- `"build": "cross-env APP_CONFIG=config/my-config.js react-scripts build"`
After updating the configuration, `yarn run build:web` to generate updated build
After updating the configuration, `yarn run build` to generate updated build
output.
<!--
Links
-->
<!-- prettier-ignore-start -->
[default-config]: https://github.com/OHIF/Viewers/blob/master/platform/viewer/public/config/default.js
[html-templates]: https://github.com/OHIF/Viewers/tree/master/platform/viewer/public/html-templates
[config-files]: https://github.com/OHIF/Viewers/tree/master/platform/viewer/public/config
<!-- prettier-ignore-end -->

4
docs/latest/frequently-asked-questions.md
View File

@ -54,7 +54,7 @@ for a product built using the platform.
If you have gone this route (or are going there), please let us know because we
would be interested to hear about your experience.
### Is The OHIF Viewer [HIPAA][hipaa] Compliant?
### Is The OHIF Viewer [HIPAA][hipaa-def] Compliant?
**NO.** The OHIF Viewer **DOES NOT** fulfill all of the criteria to become HIPAA
Compliant. It is the users responsibility to ensure compliance with applicable
@ -75,7 +75,7 @@ rules and regulations.
<!-- OTHER -->
[501k-clearance]: https://www.fda.gov/MedicalDevices/DeviceRegulationandGuidance/HowtoMarketYourDevice/PremarketSubmissions/PremarketNotification510k/
[ce-marking]: https://ec.europa.eu/growth/single-market/ce-marking_en
[hipaa]: https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act
[hipaa-def]: https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act
[new-issue]: https://github.com/OHIF/Viewers/issues/new/choose
[bug-report-template]: https://github.com/OHIF/Viewers/issues/new?assignees=&labels=Bug+Report+%3Abug%3A&template=---bug-report.md&title=
<!-- prettier-ignore-end -->

4
docs/latest/help.md
View File

@ -3,7 +3,7 @@
We all need a little help sometimes. Don't let a few roadblocks stand in the way
of you building something awesome.
## Free
## Community Support
If you're a developer looking to contribute code, documentation, or discussion;
we are more than happy to help provide clarification and answer questions via
@ -21,7 +21,7 @@ resources and must be judicious with how we allocate them. If you find yourself
in this situation and in need of assistance, it may be in your best interest to
persue paid support.
## Paid / Commercial
## Commercial Support
The Open Health Imaging Foundation does not offer commercial support, however,
some community members do offer consulting services:

2
platform/viewer/.webpack/webpack.commonjs.js
View File

@ -13,7 +13,7 @@ module.exports = (env, argv) => {
return merge(commonConfig, {
entry: {
bundle: `${SRC_DIR}/index-umd.js`,
app: `${SRC_DIR}/index-umd.js`,
},
devtool: 'source-map',
stats: {

4
platform/viewer/package.json
View File

@ -22,8 +22,8 @@
"build:viewer:ci": "cross-env NODE_ENV=production PUBLIC_URL=/pwa/ APP_CONFIG=config/netlify.js node --max_old_space_size=4096 ./../../node_modules/webpack/bin/webpack.js --config .webpack/webpack.pwa.js",
"build:viewer:demo": "cross-env NODE_ENV=production APP_CONFIG=config/demo.js HTML_TEMPLATE=rollbar.html node --max_old_space_size=4096 ./../../node_modules/webpack/bin/webpack.js --progress --config .webpack/webpack.pwa.js",
"build:viewer:package": "yarn run build:package",
"dev": "cross-env NODE_ENV=development webpack-dev-server --config .webpack/webpack.pwa.js -w",
"dev:orthanc": "cross-env NODE_ENV=development PROXY_TARGET=/dicom-web PROXY_DOMAIN=http://localhost:8042 APP_CONFIG=config/docker_nginx-orthanc.js webpack-dev-server --config .webpack/webpack.pwa.js -w",
"dev": "cross-env NODE_ENV=development webpack-dev-server --config .webpack/webpack.pwa.js --watch",
"dev:orthanc": "cross-env NODE_ENV=development PROXY_TARGET=/dicom-web PROXY_DOMAIN=http://localhost:8042 APP_CONFIG=config/docker_nginx-orthanc.js webpack-dev-server --config .webpack/webpack.pwa.js --watch",
"dev:viewer": "yarn run dev",
"start": "yarn run dev",
"test:e2e": "cypress open",

21
yarn.lock
View File

@ -1105,21 +1105,7 @@
pirates "^4.0.0"
source-map-support "^0.5.9"
"@babel/runtime@7.1.2":
version "7.1.2"
resolved "https://registry.yarnpkg.com/@babel/runtime/-/runtime-7.1.2.tgz#81c89935f4647706fc54541145e6b4ecfef4b8e3"
integrity sha512-Y3SCjmhSupzFB6wcv1KmmFucH6gDVnI30WjOcicV10ju0cZjak3Jcs67YLIXBrmZYw1xCrVeJPbycFwrqNyxpg==
dependencies:
regenerator-runtime "^0.12.0"
"@babel/runtime@7.4.3":
version "7.4.3"
resolved "https://registry.yarnpkg.com/@babel/runtime/-/runtime-7.4.3.tgz#79888e452034223ad9609187a0ad1fe0d2ad4bdc"
integrity sha512-9lsJwJLxDh/T3Q3SZszfWOTkk3pHbkmH+3KY+zwIDmsNlxsumuhS2TH3NIpktU4kNvfzy+k3eLT7aTJSPTo0OA==
dependencies:
regenerator-runtime "^0.13.2"
"@babel/runtime@^7.0.0", "@babel/runtime@^7.1.2", "@babel/runtime@^7.2.0", "@babel/runtime@^7.3.1", "@babel/runtime@^7.3.4", "@babel/runtime@^7.4.0", "@babel/runtime@^7.4.2", "@babel/runtime@^7.4.4", "@babel/runtime@^7.4.5", "@babel/runtime@^7.5.5":
"@babel/runtime@7.1.2", "@babel/runtime@7.4.3", "@babel/runtime@7.5.5", "@babel/runtime@^7.0.0", "@babel/runtime@^7.1.2", "@babel/runtime@^7.2.0", "@babel/runtime@^7.3.1", "@babel/runtime@^7.3.4", "@babel/runtime@^7.4.0", "@babel/runtime@^7.4.2", "@babel/runtime@^7.4.4", "@babel/runtime@^7.4.5", "@babel/runtime@^7.5.5":
version "7.5.5"
resolved "https://registry.yarnpkg.com/@babel/runtime/-/runtime-7.5.5.tgz#74fba56d35efbeca444091c7850ccd494fd2f132"
integrity sha512-28QvEGyQyNkB0/m2B4FU7IEZGK2NUrcMtT6BZEFALTguLk+AUT6ofsHtPk5QyjAdUkpMJ+/Em+quwz4HOt30AQ==
@ -15295,11 +15281,6 @@ regenerator-runtime@^0.11.0, regenerator-runtime@^0.11.1:
resolved "https://registry.yarnpkg.com/regenerator-runtime/-/regenerator-runtime-0.11.1.tgz#be05ad7f9bf7d22e056f9726cee5017fbf19e2e9"
integrity sha512-MguG95oij0fC3QV3URf4V2SDYGJhJnJGqvIIgdECeODCT98wSWDAJ94SSuVpYQUoTcGUIL6L4yNB7j1DFFHSBg==
regenerator-runtime@^0.12.0:
version "0.12.1"
resolved "https://registry.yarnpkg.com/regenerator-runtime/-/regenerator-runtime-0.12.1.tgz#fa1a71544764c036f8c49b13a08b2594c9f8a0de"
integrity sha512-odxIc1/vDlo4iZcfXqRYFj0vpXFNoGdKMAUieAlFYO6m/nl5e9KR/beGf41z4a1FI+aQgtjhuaSlDxQ0hmkrHg==
regenerator-runtime@^0.13.2:
version "0.13.3"
resolved "https://registry.yarnpkg.com/regenerator-runtime/-/regenerator-runtime-0.13.3.tgz#7cf6a77d8f5c6f60eb73c5fc1955b2ceb01e6bf5"