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

Docs reorganization

Browse Source
This commit is contained in:
Erik Ziegler committed 2021-07-15 09:54:01 +02:00
1 parent d6877cfcf9
commit c0df334233
152 files changed
+872 -886
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

platform/docs/docs/development/_category_.json
+1 -1
View File
@@ -1,4 +1,4 @@
{
"label": "Development",
"position": 4
"position": 5
}
platform/docs/docs/development/architecture.md
+203
View File
@@ -0,0 +1,203 @@
---
sidebar_position: 2
sidebar_label: Architecture
---
# Architecture
In order to achieve a platform that can support various workflows and be
extensible for the foreseeable future we went through extensive planning of
possible use cases and decided to significantly change and improve the
architecture.
Below, we aim to demystify that complexity by providing insight into how
`OHIF Platform` is architected, and the role each of it's dependent libraries
plays.
## Overview
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
│ ├── default # default functionalities
│ ├── cornerstone # 2D images w/ Cornerstone.js
│ ├── measurement-tracking # measurement tracking
│ ├── dicom-sr # Structured reports
│ └── dicom-pdf # View DICOM wrapped PDFs in viewport
│
├── modes
│ └── longitudinal # longitudinal measurement tracking mode
│
├── 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
```
OHIF v3 is comprised of the following components, described in detail in further
sections:
- `@ohif/viewer`: The core framework that controls extension registration, mode
composition and routing.
- `@ohif/core`: A library of useful and reusable medical imaging functionality
for the web.
- `@ohif/ui`: A library of reusable components to build OHIF-styled applications
with.
- `Extensions`: A set of building blocks for building applications. The OHIF org
maintains a few core libraries.
- `Modes`: Configuration objects that tell @ohif/viewer how to compose
extensions to build applications on different routes of the platform.
## Extensions
The `extensions` directory contains many packages that provides essential
functionalities such as rendering, study/series browsers, measurement tracking
that modes can consume to enable a certain workflow. Extensions have had their
behavior changed in `OHIF-v3` and their api is expanded. In summary:
> In `OHIF-v3`, extensions no longer automatically hook themselves to the app.
> Now, registering an extension makes its component available to `modes` that
> wish to use them. Basically, extensions in `OHIF-v3` are **building blocks**
> for building applications.
OHIF team maintains several high value and commonly used functionalities in its
own extensions. For a list of extensions maintained by OHIF,
[check out this helpful table](../platform/extensions/index.md#maintained-extensions).
As an example `default` extension provides a default viewer layout, a
study/series browser and a datasource that maps to a DICOMWeb compliant backend.
[Click here to read more about extensions!](../platform/extensions/index.md)
## Modes
The `modes` directory contains workflows that can be registered with OHIF within
certain `routes`. The mode will get used once the user opens the viewer on the
registered route.
OHIF extensions were designed to provide certain core functionalities for
building your viewer. However, often in medical imaging we face a specific use
case in which we are using some core functionalities, adding our specific UI,
and use it in our workflows. Previously, to achieve this you had to create an
extension to add have such feature. `OHIF-v3` introduces `Modes` to enable
building such workflows by re-using the core functionalities from the
extensions.
Some common workflows may include:
- Measurement tracking for lesions
- Segmentation of brain abnormalities
- AI probe mode for detecting prostate cancer
In the mentioned modes above, they will share the same core rendering module
that the `default` extension provides. However, segmentation mode will require
segmentation tools which is not needed for the other two. As you can see, modes
are a layer on top of extensions, that you can configure in order to achieve
certain workflows.
To summarize the difference between extensions and modes in `OHIF-v3` and
extensions in `OHIF-v2`
> - `Modes` are configuration objects that tell _@ohif/viewer_ how to compose
> extensions to build applications on different routes of the platform.
> - In v2 extensions are “plugins” that add functionality to a core viewer.
> - In v3 extensions are building blocks that a mode uses to build an entire
> viewer layout.
[Click here to read more about modes!](../platform/modes/index.md)
## Platform
### `@ohif/viewer`
This library is the core library which consumes modes and extensions and builds
an application. Extensions can be passed in as app configuration and will be
consumed and initialized at the appropriate time by the application. Upon
initialization the viewer will consume extensions and modes and build up the
route desired, these can then be accessed via the study list, or directly via
url parameters.
Upon release modes will also be plugged into the app via configuration, but this
is still an area which is under development/discussion, and they are currently
pulled from the window in beta.
Future ideas for this framework involve only adding modes and fetching the
required extension versions at either runtime or build time, but this decision
is still up for discussion.
### `@ohif/core`
OHIF core is a carefully maintained and tested set of web-based medical imaging
functions and classes. This library includes managers and services used from
within the viewer app.
OHIF core is largely similar to the @ohif/core library in v2, however a lot of
logic has been moved to extensions: however all logic about DICOMWeb and other
data fetching mechanisms have been pulled out, as these now live in extensions,
described later.
### `@ohif/ui`
Firstly, a large time-consumer/barrier for entry we discovered was building new
UI in a timely manner that fit OHIF’s theme. For this reason we have built a new
UI component library which contains all the components one needs to build their
own viewer.
These components are presentational only, so you can reuse them with whatever
logic you desire. As the components are presentational, you may swap out
@ohif/ui for a custom UI library with conforming API if you wish to white label
the viewer. The UI library is here to make development easier and quicker, but
it is not mandatory for extension components to use.
[Check out our component library!](https://react.ohif.org/)
## Overview of the architecture
OHIF-v3 architecture can be seen in the following figure. We will explore each
piece in more detail.
![mode-archs](../assets/img/mode-archs.png)
## Common Questions
> 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. `@ohif/ui` would then become a guide for the components
you would need to recreate.
> When I want to implement a functionality, should it be in the mode or in an
> extension?
This is a great question. Modes are designed to consume extensions, so you
should implement your functionality in one of the modules of your new extension,
and let the mode to consume it. This way, in future, if you needed another mode
that utilizes the same functionality, you can easily hook the extension to the
new mode as well.
<!--
Links
-->
<!-- prettier-ignore-start -->
[monorepo]: https://github.com/OHIF/Viewers/issues/768
[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/
[configuration]: ../configuration/index.md
[extensions]: ../platform/extensions/index.md
[core-github]: https://github.com/OHIF/viewers/platform/core
[ui-github]: https://github.com/OHIF/Viewers/tree/master/platform/ui
<!-- prettier-ignore-end -->
platform/docs/docs/development/continous-integration.md
+2 -10
View File
@@ -1,7 +1,8 @@
---
sidebar_position: 3
sidebar_position: 6
sidebar_label: Continous Integration
---
# Continous Integration (CI)
This repository uses `CircleCI` and `Netlify` for continous integration.
@@ -29,7 +30,6 @@ The PR_CHECKS workflow (Pull Request Checks) runs our automated unit and
end-to-end tests for every code check-in. These tests must all pass before code
can be merged to our `master` branch.
![PR_CHECKS](../assets/img/WORKFLOW_PR_CHECKS.png)
### Workflow: PR_OPTIONAL_DOCKER_PUBLISH
@@ -38,8 +38,6 @@ The PR_OPTIONAL_DOCKER_PUBLISH workflow allows for "manual approval" to publish
the pull request as a tagged docker image. This is helpful when changes need to
be tested with the Google Adapter before merging to `master`.
![PR_Workflow](../assets/img/WORKFLOW_PR_OPTIONAL_DOCKER_PUBLISH.png)
> NOTE: This workflow will fail unless it's for a branch on our `upstream`
@@ -53,10 +51,8 @@ It uses the Netlify CLI to deploy assets created as part of the repository's PWA
Build process (`yarn run build`). The workflow allows for "Manual Approval" to
promote the build to `STAGING` and `PRODUCTION` environments.
![WORKFLOW_DEPLOY](../assets/img/WORKFLOW_DEPLOY.png)
| Environment | Description | URL |
| ----------- | ---------------------------------------------------------------------------------- | --------------------------------------------- |
| Development | Always reflects latest changes on `master` branch. | [Netlify][netlify-dev] / [OHIF][ohif-dev] |
@@ -76,12 +72,8 @@ GitHub hosts the `gh-pages` branch with GitHub Pages.
- Extension Packages: https://github.com/ohif/viewers/#extensions
- Documentation: https://docs.ohif.org/
![WORKFLOW_RELEASE](../assets/img/WORKFLOW_RELEASE.png)
<!--
LINKS
-->
platform/docs/docs/development/contributing.md
+9 -12
View File
@@ -1,7 +1,8 @@
---
sidebar_position: 2
sidebar_position: 3
sidebar_label: Contributing
---
# Contributing
## How can I help?
@@ -12,7 +13,7 @@ should be implemented, please don't hesitate to create a new issue. At a
minimum, you may want to read the following documentation:
- [Getting Started](/development/getting-started.md)
- [Architecture](../architecture.md)
- [Architecture](./architecture.md)
Pull requests that are:
@@ -49,9 +50,8 @@ On your local file system:
- [`yarn link`](https://yarnpkg.com/en/docs/cli/link)
- `yarn run dev`
- Open a new terminal/shell
- Navigate to `ohif/viewers` (the root of ohif project)
* Open a new terminal/shell
* Navigate to `ohif/viewers` (the root of ohif project)
- `yarn install`
- [`yarn link cornerstone-tools`](https://yarnpkg.com/en/docs/cli/link)
- `yarn run dev`
@@ -59,12 +59,8 @@ On your local file system:
As you make changed to `cornerstone-tools`, and it's output is rebuilt, you
should see the following behavior:
![tools](..//assets/img/cornerstone-tools-link.gif)
If you wish to stop using your local package, run the following commands in the
`ohif/viewers` repository root:
@@ -101,9 +97,10 @@ there are a lot of factors that can influence the behavior of our development
server and bundler. If you encounter issues not addressed here, please don't
hesitate to reach out on GitHub.
Sometimes you might encounter a situation where the linking doesn't work as expected.
This might happen when there are multiple linked packages with the same name.
You can [remove][unlink] the linked packages inside yarn and try again.
Sometimes you might encounter a situation where the linking doesn't work as
expected. This might happen when there are multiple linked packages with the
same name. You can [remove][unlink] the linked packages inside yarn and try
again.
## Any guidance on submitting changes?
platform/docs/docs/development/getting-started.md
+2 -3
View File
@@ -2,6 +2,7 @@
sidebar_position: 1
sidebar_label: Getting Started
---
# Getting Started
## Setup
@@ -74,12 +75,10 @@ You should see the following output:
### 🎉 Celebrate 🎉
<div style={{padding:"56.25% 0 0 0", position:"relative"}}>
<iframe src="https://player.vimeo.com/video/545988245?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="measurement-report"></iframe>
</div>
### Building for Production
> More comprehensive guides for building and publishing can be found in our
@@ -97,7 +96,7 @@ yarn run build:package
- If you receive a _"No Studies Found"_ message and do not see your studies, try
changing the Study Date filters to a wider range.
- If you see a 'Loading' message which never resolves, check your browser
- If you see a 'Loading' message which never resolves, check your browser's
JavaScript console inside the Developer Tools to identify any errors.
<!--
platform/docs/docs/development/our-process.md
+156
View File
@@ -0,0 +1,156 @@
---
sidebar_position: 2
sidebar_label: Issue & PR Triage Process
---
# Our Process
Our process is a living, breathing thing. We strive to have regular
[retrospectives][retrospective] that help us shape and adapt our process to our
team's current needs. This document attempts to capture the broad strokes of
that process in an effort to:
- Strengthen community member involvement and understanding
- Welcome feedback and helpful suggestions
## Issue Triage
[GitHub issues][gh-issues] are the best way to provide feedback, ask questions,
and suggest changes to the OHIF Viewer's core team. Community issues generally
fall into one of three categories, and are marked with a `triage` label when
created.
| Issue Template Name | Description |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| Community: Report 🐛 | Describe a new issue; Provide steps to reproduce; Expected versus actual result? |
| Community: Request ✋ | Describe a proposed new feature. Why should it be implemented? What is the impact/value? |
| Community: Question ❓ | Seek clarification or assistance relevant to the repository. |
_table 1. issue template names and descriptions_
Issues that require `triage` are akin to support tickets. As this is often our
first contact with would-be adopters and contributors, it's important that we
strive for timely responses and satisfactory resolutions. We attempt to
accomplish this by:
1. Responding to issues requiring `triage` at least once a week
2. Create new "official issues" from "community issues"
3. Provide clear guidance and next steps (when applicable)
4. Regularly clean up old (stale) issues
> 🖋 Less obviously, patterns in the issues being reported can highlight areas
> that need improvement. For example, users often have difficulty navigating
> CORS issues when deploying the OHIF Viewer -- how do we best reduce our ticket
> volume for this issue?
### Backlogged Issues
Community issues serve as vehicles of discussion that lead us to "backlogged
issues". Backlogged issues are the distilled and actionable information
extracted from community issues. They contain the scope and requirements
necessary for hand-off to a core-team (or community) contributor ^\_^
| Category | Description | Labels |
| -------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Bugs | An issue with steps that produce a bug (an unexpected result). | [Bug: Verified 🐛][label-bug] |
| Stories | A feature/enhancement with a clear benefit, boundaries, and requirements. | [Story 🙌][label-story] |
| Tasks | Changes that improve [UX], [DX], or test coverage; but don't impact application behavior | [Task: CI/Tooling 🤖][label-tooling], [Task: Docs 📖][label-docs], [Task: Refactor 🛠][label-refactor], [Task: Tests 🔬][label-tests] |
_table 2. backlogged issue types ([full list of labels][gh-labels])_
## Issue Curation (["backlog grooming"][groom-backlog])
If a [GitHub issue][gh-issues] has a `bug`, `story`, or `task` label; it's on
our backlog. If an issue is on our backlog, it means we are, at the very least,
committed to reviewing any community drafted Pull Requests to complete the
issue. If you're interested in seeing an issue completed but don't know where to
start, please don't hesitate to leave a comment!
While we don't yet have a long-term or quarterly road map, we do regularly add
items to our ["Active Development" GitHub Project Board][gh-board]. Items on
this project board are either in active development by Core Team members, or
queued up for development as in-progress items are completed.
> 🖋 Want to contribute but not sure where to start? Check out [Up for
> grabs][label-grabs] issues and our [Contributing
> documentation][contributing-docs]
## Contributions (Pull Requests)
Incoming Pull Requests (PRs) are triaged using the following labels. Code review
is performed on all PRs where the bug fix or added functionality is deemed
appropriate:
| Labels | Description |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Classification** | |
| [PR: Bug Fix][label-bug] | Filed to address a Bug. |
| [PR: Draft][draft] | Filed to gather early feedback from the core team, but which is not intended for merging in the short term. |
| **Review Workflow** | |
| [PR: Awaiting Response 💬][awaiting-response] | The core team is waiting for additional information from the author. |
| [PR: Awaiting Review 👀][awaiting-review] | The core team has not yet performed a code review. |
| [PR: Awaiting Revisions 🖊][awaiting-revisions] | Following code review, this label is applied until the author has made sufficient changes. |
| **QA** | |
| [PR: Awaiting User Cases 💃][awaiting-stories] | The PR code changes need common language descriptions of impact to end users before the review can start |
| [PR: No UX Impact 🙃][no-ux-impact] | The PR code changes do not impact the user's experience |
We rely on GitHub Checks and integrations with third party services to evaluate
changes in code quality and test coverage. Tests must pass and User cases must
be present (when applicable) before a PR can be merged to master, and code
quality and test coverage must not changed by a significant margin. For some
repositories, visual screenshot-based tests are also included, and video
recordings of end-to-end tests are stored for later review.
[You can read more about our continous integration efforts here](/development/continous-integration.md)
## Releases
Releases are made automatically based on the type of commits which have been
merged (major.minor.patch). Releases are automatically pushed to NPM. Release
notes are automatically generated. Users can subscribe to GitHub and NPM
releases.
We host development, staging, and production environments for the Progressive
Web Application version of the OHIF Viewer. [Development][ohif-dev] always
reflects the latest changes on our master branch. [Staging][ohif-stage] is used
to regression test a release before a bi-weekly deploy to our [Production
environment][ohif-prod].
Important announcements are made on GitHub, tagged as Announcement, and pinned
so that they remain at the top of the Issue page.
The Core team occasionally performs full manual testing to begin the process of
releasing a Stable version. Once testing is complete, the known issues are
addressed and a Stable version is released.
<!--
LINKS
-->
<!-- prettier-ignore-start -->
[groom-backlog]: https://www.agilealliance.org/glossary/backlog-grooming
[retrospective]: https://www.atlassian.com/team-playbook/plays/retrospective
[gh-issues]: https://github.com/OHIF/Viewers/issues/new/choose
[gh-labels]: https://github.com/OHIF/Viewers/labels
<!-- Issue Labels -->
[label-story]: https://github.com/OHIF/Viewers/labels/Story%20%3Araised_hands%3A
[label-tooling]: https://github.com/OHIF/Viewers/labels/Task%3A%20CI%2FTooling%20%3Arobot%3A
[label-docs]: https://github.com/OHIF/Viewers/labels/Task%3A%20Docs%20%3Abook%3A
[label-refactor]: https://github.com/OHIF/Viewers/labels/Task%3A%20Refactor%20%3Ahammer_and_wrench%3A
[label-tests]: https://github.com/OHIF/Viewers/labels/Task%3A%20Tests%20%3Amicroscope%3A
[label-bug]: https://github.com/OHIF/Viewers/labels/Bug%3A%20Verified%20%3Abug%3A
<!-- PR Labels -->
[draft]: https://github.com/OHIF/Viewers/labels/PR%3A%20Draft
[awaiting-response]: https://github.com/OHIF/Viewers/labels/PR%3A%20Awaiting%20Response%20%3Aspeech_balloon%3A
[awaiting-review]: https://github.com/OHIF/Viewers/labels/PR%3A%20Awaiting%20Review%20%3Aeyes%3A
[awaiting-stories]: https://github.com/OHIF/Viewers/labels/PR%3A%20Awaiting%20UX%20Stories%20%3Adancer%3A
[awaiting-revisions]: https://github.com/OHIF/Viewers/labels/PR%3A%20Awaiting%20Revisions%20%3Apen%3A
[no-ux-impact]: https://github.com/OHIF/Viewers/labels/PR%3A%20No%20UX%20Impact%20%3Aupside_down_face%3A
<!-- -->
[ohif-dev]: https://viewer-dev.ohif.org
[ohif-stage]: https://viewer-stage.ohif.org
[ohif-prod]: https://viewer.ohif.org
[gh-board]: https://github.com/OHIF/Viewers/projects/4
[label-grabs]: https://github.com/OHIF/Viewers/issues?q=is%3Aissue+is%3Aopen+label%3A%22Up+For+Grabs+%3Araising_hand_woman%3A%22
[contributing-docs]: ./development/contributing.md
<!-- prettier-ignore-end -->
platform/docs/docs/development/testing.md
+15 -15
View File
@@ -1,31 +1,35 @@
---
sidebar_position: 4
sidebar_position: 5
sidebar_label: Testing
---
# Running Tests for OHIF
We introduce here various test types that is available
for OIHF, and how to run each test in order to make sure your contribution
hasn't broken any existing functionalities. Idea and philosophy of each testing category is discussed in the second
part of this page.
We introduce here various test types that is available for OHIF, and how to run
each test in order to make sure your contribution hasn't broken any existing
functionalities. Idea and philosophy of each testing category is discussed in
the second part of this page.
## Unit test
To run the unit test:
```bash
yarn run test:unit:ci
```
Note: You should have already installed all the packages with `yarn install`.
Running unit test will generate a report at the end showing the successful and
unsuccessful tests with detailed explanations.
## End-to-end test
For running the OHIF e2e test you need to run the following steps:
- Create a mini-pacs for OHIF to access the images for testing. We download
and run our lightweight implementation which provides a collection of DICOM studies ([source code][mini-pacs]).
- Create a mini-pacs for OHIF to access the images for testing. We download and
run our lightweight implementation which provides a collection of DICOM
studies ([source code][mini-pacs]).
```bash
docker run -p 5985:5985 -p 5984:5984 -e USE_POUCHDB=true -e DB_SERVER=http://0.0.0.0 ohif/viewer-testdata:0.1-test
@@ -35,7 +39,8 @@ and run our lightweight implementation which provides a collection of DICOM stud
![](../assets/img/docker-pacs.png)
- Open a new terminal, navigate to the OHIF project, and run OHIF with the dicom-server config
- Open a new terminal, navigate to the OHIF project, and run OHIF with the
dicom-server config
```bash
APP_CONFIG=config/dicomweb-server.js yarn start
@@ -45,7 +50,7 @@ and run our lightweight implementation which provides a collection of DICOM stud
![OHIF-e2e-test-studies](../assets/img/OHIF-e2e-test-studies.png)
- Open a new terminal inside the OIHF project, and run the e2e cypress test
- Open a new terminal inside the OHIF project, and run the e2e cypress test
```bash
yarn run test:e2e
@@ -62,11 +67,6 @@ and run our lightweight implementation which provides a collection of DICOM stud
![e2e-cypress-final](../assets/img/e2e-cypress-final.png)
## Testing Philosiphy
> Testing is an opinionated topic. Here is a rough overview of our testing