From 51b4e601616a268458c8585365e64be40e0a987c Mon Sep 17 00:00:00 2001 From: David Connaughton <15805713+eolasd@users.noreply.github.com> Date: Tue, 28 Apr 2020 06:11:35 +1000 Subject: [PATCH] docs: updated deployment section with info for using JSON (#1676) * update deploy section with non-dicomweb info * fix typo and add info re. case sensitive json * Add CORS info and reformat inline links Co-authored-by: eolasd --- docs/latest/deployment/index.md | 103 +++++++++++++++++++++++++++++++- 1 file changed, 100 insertions(+), 3 deletions(-) diff --git a/docs/latest/deployment/index.md b/docs/latest/deployment/index.md index 6e811551b..8959fac7d 100644 --- a/docs/latest/deployment/index.md +++ b/docs/latest/deployment/index.md @@ -127,10 +127,107 @@ appropriate headers. You can find an example of this setup in our #### What if my archive doesn't support DicomWeb? -> This is possible to do with the OHIF Viewer, but not as straightforward. Look -> out for documentation on this subject in the near future. +It's possible to supply all Study data via JSON format, in the event you do not have a DicomWeb endpoint. +You can host all of the relevant files on any web accessible server (Amazon S3, Azure Blob Storage, Local file server etc.) + +This JSON is supplied via the '?url=' query parameter. +It should reference an endpoint that returns **application/json** formatted text. + +If you do not have an API, you can simply return a text file containing the JSON from any web server. + + +You tell the OHIF viewer to use JSON by appending the `'?url='` query to the `/Viewer` route: + +eg. `https://my-test-ohif-server/viewer?url=https://my-json-server/study-uid.json` + +The returned JSON object must contain a single root object with a 'studies' array. + + +*Sample JSON format:* +```JSON +{ + "studies": [ + { + "StudyInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.78", + "StudyDescription": "BRAIN SELLA", + "StudyDate": "20010108", + "StudyTime": "120022", + "PatientName": "MISTER^MR", + "PatientId": "832040", + "series": [ + { + "SeriesDescription": "SAG T-1", + "SeriesInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.121", + "SeriesNumber": 2, + "SeriesDate": "20010108", + "SeriesTime": "120318", + "Modality": "MR", + "instances": [ + { + "metadata": { + "Columns": 512, + "Rows": 512, + "InstanceNumber": 3, + "AcquisitionNumber": 0, + "PhotometricInterpretation": "MONOCHROME2", + "BitsAllocated": 16, + "BitsStored": 16, + "PixelRepresentation": 1, + "SamplesPerPixel": 1, + "PixelSpacing": [0.390625, 0.390625], + "HighBit": 15, + "ImageOrientationPatient": [0,1,0,0,0,-1], + "ImagePositionPatient": [11.600000,-92.500000, 98.099998], + "FrameOfReferenceUID": "1.2.840.113619.2.5.1762583153.223134.978956938.470", + "ImageType": ["ORIGINAL","PRIMARY","OTHER"], + "Modality": "MR", + "SOPInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.124", + "SeriesInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.121", + "StudyInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.78" + }, + "url": "dicomweb://s3.amazonaws.com/lury/MRStudy/1.2.840.113619.2.5.1762583153.215519.978957063.124.dcm" + } + ] + } + ] + } + ] +} +``` +More info on this JSON format can be found here [Issue #1500](https://github.com/OHIF/Viewers/issues/1500) + + +**Implementation Notes:** + +1. When hosting the viewer, you will also need to host a /viewer route on the server - or the browser may not be able to find the route. +2. For each instance url (dicom object) in the returned JSON, you must prefix the `url` with `dicomweb:` in order for the cornerstone image loader to retrieve it correctly. + eg. `https://image-server/my-image.dcm` ---> `dicomweb:https://image-server/my-image.dcm` +3. The JSON format above is compatible with >= v3.7.8 of the application. Older versions of the viewer used a different JSON format. As of 20/04/20 the public [https://viewer.ohif.org/] is a pre 3.0 version that does not support this format yet. +4. The JSON format is case-sensitive. Please ensure you have matched casing with the naturalised Dicom format referenced in [Issue #1500](https://github.com/OHIF/Viewers/issues/1500). + +*CORS Issues (Cross-Origin Resource Sharing)* + +If you host a JSON API or Images on a different domain from the the app itself, you will likely have CORS issues. This will also happen when testing from Localhost and reaching out to remote servers. +Even if the domain is the same, different ports, subdomains or protocols (https vs http) will also cause CORS errors. +You will to need add a configuration on each server hosting these assets to allow your App server origin. + +For example: + +Lets assume your application is hosted on `https://my-ohif-server.com`. + +Your JSON API is hosted on `https://my-json-api.aws.com` + +And your images are stored on Amazon S3 at `https://my-s3-bucket.aws.com` + +When you first start your application, browsing to `https://my-ohif-server.com/viewer?url=https://my-json-api.aws.com/api/my-json-study-info.json`, you will likely get a CORS error in the browser console as it tries to connect to `https://my-json-api.aws.com`. + +Adding a setting on the JSON server to allow the CORS origin = `https://my-ohif-server.com` should solve this. + +Next, you will likely get a similar CORS error, as the browser tries to go to `https://my-s3-bucket.aws.com`. +You will need to go to the S3 bucket configuration, and add a CORS setting to allow origin = `https://my-ohif-server.com`. + +Essentially, whenever the application connects to a remote resource, you will need to add the applications url to the allowed CORS Origins on that resource. Adding an origin similar to https://localhost:3000 will also allow for local testing. -... ### Securing Your Data