feat(URL): add param for initial series and sop uids to display (#3265)

* feat: Allow navigating to a specified series and sop instance

This was a feature in OHIF v2, so adding it to v3, albeit with new
parameters.

feat: Allow comma separated as well as repeated args params

* docs

* Test fixes

* feat: Navigate to SOP selected - PR fixes

* Updated docs

* PR fixes

platform/docs/docs/configuration/url.md

@@ -110,17 +110,46 @@ You can open more than one study in the Viewer by adding the `StudyInstanceUIDs`
 :::tip
 
 You can ues this feature to open a current and prior study in the Viewer.
-Read more in the [Hanging Protocol Module](../platform/extensions/modules/hpModule.md#matching-on-prior-study-with-uid) section
+Read more in the [Hanging Protocol Module](../platform/extensions/modules/hpModule.md#matching-on-prior-study-with-uid) section.  You can also use commas to separate
+values.
 
 :::
 
 
-### SeriesInstanceUIDs
+### SeriesInstanceUID and initialSeriesInstanceUID
 
-Sometimes you need to only open a specific series in a study, you can do that by
+Sometimes you need to only retrieve a specific series in a study, you can do
+that by providing series level QIDO query parameters in the URL such as
+SeriesInstanceUID or SeriesNumber.  This does NOT work with instance or study
+level parameters.  For example:
 
 ```js
-/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125095722.1&SeriesInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125095748.1
+http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125113417.1&SeriesInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125113545.4
 ```
 
-This will only open the viewer with one series (one displaySet).
+This will only open the viewer with one series (one displaySet) loaded, and no
+queries made for any other series.
+
+Alternatively, sometimes you want to just open the study on a specified series
+and/or display a particular sop instance, which you can accomplish using:
+`initialSeriesInstanceUID` and/or `initialSOPInstanceUID`
+to select the series to open on, but allowing other
+series to be present in the study browser panel.  This is the same behaviour
+as in OHIF 2.0, albeit on different URL parameters.  For example:
+
+```js
+http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125113417.1&initialSeriesInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125113545.4
+```
+
+Note that you can combine these, if you want to load a specific set of series
+plus show an initial one as the first one selected, for example:
+
+```js
+http://localhost:3000/viewer?StudyInstanceUIDs=1.3.6.1.4.1.25403.345050719074.3824.20170125113417.1&SeriesInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125113545.4&initialSopInstanceUID=1.3.6.1.4.1.25403.345050719074.3824.20170125113546.1
+```
+
+### hangingProtocolId
+
+You can select the initial hanging protocol to apply by using the
+hangingProtocolId parameter.  The selected parameter must be available in a
+hangingProtocolModule registration, but does not have to be active.

platform/docs/docs/platform/services/data/HangingProtocolService.md

@@ -218,7 +218,8 @@ the display set is the same as the other viewports, but the
 from the display set selector which isn't already filling a view.
 
 ## Custom Attribute
-In some situations, you might want to match based on a custom attribute and not the DICOM tags. For instance,
+In some situations, you might want to match based on a custom
+attribute and not the DICOM tags. For instance,
 if you have assigned a `timepointId` to each study, and you want to match based on it.
 Good news is that, in `OHIF-v3` you can define you custom attribute and use it for matching.
 
@@ -294,3 +295,18 @@ function modeFactory() {
   };
 }
 ```
+
+### Custom Attributes for Viewport Options
+
+The custom attributes can also be used for viewport options.  This example,
+from the default hanging protocol navigates the image to the image
+specified in the URL:
+
+```javascript
+viewportOptions: {
+  initialImageOptions: {
+    // custom attribute name is selected by 'custom'
+    custom: 'sopInstanceLocation',
+    // This is the value returned if the above doesn't return anything
+    defaultValue: { index: 5 },
+```