fix(hp): Make the updated hanging protocol compatible with modes (#2971)

There had been a change made to make the hanging protocols
auto initialize, but that caused problems on mode init
because the couldn't specify the hanging protocols any longer.
THis change restores that, and also improves the API a little
bit by allowing the display set selectors to be specified by id
instead of positionally.

fix(hp):PR Review Comments

fix(hp):Unit test and docs

platform/core/src/extensions/ExtensionManager.js

@@ -287,7 +287,10 @@ export default class ExtensionManager {
   _initHangingProtocolsModule = (extensionModule, extensionId) => {
     const { HangingProtocolService } = this._servicesManager.services;
     extensionModule.forEach(({ id, protocol }) => {
-      HangingProtocolService.addProtocol(id, protocol);
+      if (protocol) {
+        // Only auto-register if protocol specified, otherwise let mode register
+        HangingProtocolService.addProtocol(id, protocol);
+      }
     });
   };
 

platform/core/src/services/HangingProtocolService/HPMatcher.js

@@ -11,7 +11,7 @@ import validate from './lib/validator';
  */
 const match = (
   metadataInstance,
-  rules,
+  rules = [],
   customAttributeRetrievalCallbacks,
   options
 ) => {

platform/core/src/services/HangingProtocolService/HangingProtocolService.test.js

@@ -2,31 +2,40 @@ import HangingProtocolServiceClass from './HangingProtocolService';
 
 const testProtocol = {
   id: 'test',
-  locked: true,
   hasUpdatedPriorsInformation: false,
   name: 'Default',
-  createdDate: '2021-02-23T19:22:08.894Z',
-  modifiedDate: '2021-02-23T19:22:08.894Z',
-  availableTo: {},
-  editableBy: {},
-  toolGroupIds: ['ctToolGroup', 'ptToolGroup'],
-  imageLoadStrategy: 'interleaveTopToBottom', // "default" , "interleaveTopToBottom",  "interleaveCenter"
   protocolMatchingRules: [
     {
-      id: 'wauZK2QNEfDPwcAQo',
-      weight: 1,
       attribute: 'StudyDescription',
       constraint: {
-        contains: {
-          value: 'PETCT',
-        },
+        contains: 'PETCT',
       },
-      required: false,
     },
   ],
+  displaySetSelectors: {
+    displaySetSelector: {
+      seriesMatchingRules: [
+        {
+          weight: 1,
+          attribute: 'Modality',
+          constraint: {
+            equals: 'CT',
+          },
+          required: true,
+        },
+        {
+          weight: 1,
+          attribute: 'numImageFrames',
+          constraint: {
+            greaterThan: 10,
+          },
+        },
+      ],
+      studyMatchingRules: [],
+    },
+  },
   stages: [
     {
-      id: 'hYbmMy3b7pz7GLiaT',
       name: 'default',
       viewportStructure: {
         layoutType: 'grid',
@@ -35,29 +44,6 @@ const testProtocol = {
           columns: 1,
         },
       },
-      displaySets: [
-        {
-          id: 'displaySet',
-          seriesMatchingRules: [
-            {
-              weight: 1,
-              attribute: 'Modality',
-              constraint: {
-                equals: 'CT',
-              },
-              required: true,
-            },
-            {
-              weight: 1,
-              attribute: 'numImageFrames',
-              constraint: {
-                greaterThan: 10,
-              },
-            },
-          ],
-          studyMatchingRules: [],
-        },
-      ],
       viewports: [
         {
           viewportOptions: {
@@ -83,7 +69,7 @@ const testProtocol = {
           },
           displaySets: [
             {
-              id: 'displaySet',
+              id: 'displaySetSelector',
             },
           ],
         },

platform/core/src/services/HangingProtocolService/HangingProtocolService.ts

@@ -19,6 +19,8 @@ class HangingProtocolService {
   studies: StudyMetadata[];
   // stores all the protocols (object or function that returns an object) in a map
   protocols: Map<string, Protocol>;
+  // Contains the list of currently active keys
+  activeProtocolIds: string[];
   // the current protocol that is being applied to the viewports in object format
   protocol: HangingProtocol.Protocol;
   stage: number;
@@ -123,8 +125,9 @@ class HangingProtocolService {
     // this.protocols is a map of protocols with the protocol id as the key
     // and the protocol or a function that returns a protocol as the value
     const protocols = [];
+    const keys = this.activeProtocolIds || this.protocols.keys();
     // @ts-ignore
-    for (const protocolId of this.protocols.keys()) {
+    for (const protocolId of keys) {
       const protocol = this.getProtocolById(protocolId);
       if (protocol) {
         protocols.push(protocol);
@@ -164,7 +167,8 @@ class HangingProtocolService {
 
   /**
    * It adds a protocol to the protocols map object. If a protocol with the given
-   * id already exists, warn the user and overwrite it.
+   * id already exists, warn the user and overwrite it.  This can be used to
+   * set a new "default" protocol.
    *
    * @param {string} protocolId - The id of the protocol.
    * @param {Protocol} protocol - Protocol - This is the protocol that you want to
@@ -184,6 +188,40 @@ class HangingProtocolService {
     this.protocols.set(protocolId, protocol);
   }
 
+  /**
+   * Add a given protocol object as active.
+   * If active protocols ids is null right now, then the specified
+   * protocol will become the only active protocol.
+   */
+  public addActiveProtocol(id: string): void {
+    if (!id) {
+      return;
+    }
+    if (!this.activeProtocolIds) {
+      this.activeProtocolIds = [];
+    }
+    this.activeProtocolIds.push(id);
+  }
+
+  /**
+   * Sets the active hanging protocols to use, by name.  If the value is empty,
+   * then resets the active protocols to all the named items.
+   */
+  public setActiveProtocols(
+    hangingProtocol?: string[] | string
+  ): void {
+    if (!hangingProtocol || !hangingProtocol.length) {
+      this.activeProtocolIds = null;
+      console.log('No active protocols, setting all to active');
+      return;
+    }
+    if (typeof hangingProtocol === 'string') {
+      this.setActiveProtocols([hangingProtocol]);
+      return;
+    }
+    this.activeProtocolIds = [...hangingProtocol];
+  }
+
   /**
    * Run the hanging protocol decisions tree on the active study,
    * studies list and display sets, firing a hanging protocol event when
@@ -208,7 +246,7 @@ class HangingProtocolService {
       this.customAttributeRetrievalCallbacks
     );
 
-    if (protocolId) {
+    if (protocolId && typeof protocolId === 'string') {
       const protocol = this.getProtocolById(protocolId);
       this._setProtocol(protocol);
       return;
@@ -504,6 +542,8 @@ class HangingProtocolService {
       );
     }
 
+    const { displaySetSelectors = {} } = this.protocol;
+
     // Retrieve the current stage
     const stageModel = this._getCurrentStageModel();
 
@@ -513,7 +553,6 @@ class HangingProtocolService {
       !stageModel ||
       !stageModel.viewportStructure ||
       !stageModel.viewports ||
-      !stageModel.displaySets ||
       !stageModel.viewports.length
     ) {
       console.log('Stage cannot be applied', stageModel);
@@ -541,17 +580,27 @@ class HangingProtocolService {
     });
 
     // Matching the displaySets
-    for (const displaySet of stageModel.displaySets) {
-      // skip matching if already matched
-      if (this.displaySetMatchDetails.has(displaySet.id)) {
-        continue;
-      }
+    for (const viewport of stageModel.viewports) {
+      for (const displaySet of viewport.displaySets) {
+        const { id: displaySetId } = displaySet;
+        // skip matching if already matched
+        if (this.displaySetMatchDetails.has(displaySetId)) {
+          continue;
+        }
+        const displaySetSelector = displaySetSelectors[displaySetId];
 
-      const { bestMatch, matchingScores } = this._matchImages(displaySet);
-      this.displaySetMatchDetails.set(displaySet.id, bestMatch);
+        if (!displaySetSelector) {
+          console.warn('No display set selector for', displaySetId);
+          continue;
+        }
+        const { bestMatch, matchingScores } = this._matchImages(
+          displaySetSelector
+        );
+        this.displaySetMatchDetails.set(displaySetId, bestMatch);
 
-      if (bestMatch) {
-        bestMatch.matchingScores = matchingScores;
+        if (bestMatch) {
+          bestMatch.matchingScores = matchingScores;
+        }
       }
     }
 
@@ -564,8 +613,6 @@ class HangingProtocolService {
       // but it is a info to locate the displaySet from the displaySetService
       const displaySetsInfo = [];
       viewport.displaySets.forEach(
-        // Todo: why do we have displaySetIndex here? It is not used in the protocol
-        // definition
         ({ id, displaySetIndex = 0, options: displaySetOptions }) => {
           const viewportDisplaySetMain = this.displaySetMatchDetails.get(id);
           // Use the display set index to allow getting the "next" match, eg
@@ -612,11 +659,7 @@ class HangingProtocolService {
     // level matching needs to be added in future
 
     // Todo: handle fusion viewports by not taking the first displaySet rule for the viewport
-    const {
-      studyMatchingRules = [],
-      seriesMatchingRules,
-      findAll = false,
-    } = displaySetRules;
+    const { studyMatchingRules = [], seriesMatchingRules } = displaySetRules;
 
     const matchingScores = [];
     let highestStudyMatchingScore = 0;

platform/core/src/services/HangingProtocolService/ProtocolEngine.js

@@ -131,12 +131,14 @@ export default class ProtocolEngine {
     // If no matches were found, select the default protocol if provided
     // if not select the first protocol in the list
     if (!matched.length) {
+      const protocol =
+        this.protocols.find(protocol => protocol.id === 'default') ??
+        this.protocols[0];
+      console.log('No protocol matches, defaulting to', protocol);
       return [
         {
-          score: 1,
-          protocol:
-            this.protocols.find(protocol => protocol.id === 'default') ??
-            this.protocols[0],
+          score: 0,
+          protocol,
         },
       ];
     }

platform/core/src/types/HangingProtocol.ts

@@ -48,11 +48,21 @@ type ViewportStructure = {
   };
 };
 
-type DisplaySet = {
-  id: string;
-  imageMatchingRules: MatchingRule[];
+/**
+ * Selects the display sets to apply for a given id.
+ * This is a set of rules which match the study and display sets
+ * and then provides an id for them so that they can re-used in different
+ * viewports.
+ * The matches are done lazily, so if a stage doesn't need a given match,
+ * it won't be selected.
+ */
+type DisplaySetSelector = {
+  // The image matching rule (not currently implemented) selects which image to
+  // display initially, only for stack views.
+  imageMatchingRules?: MatchingRule[];
+  // The matching rules to choose the display sets at the series level
   seriesMatchingRules: MatchingRule[];
-  studyMatchingRules: MatchingRule[];
+  studyMatchingRules?: MatchingRule[];
 };
 
 type SyncGroup = {
@@ -75,11 +85,17 @@ type ViewportOptions = {
   viewportId?: string;
   initialImageOptions?: initialImageOptions;
   syncGroups?: SyncGroup[];
-            customViewportProps? : Record<string, unknown>;
+  customViewportProps?: Record<string, unknown>;
 };
 
 type DisplaySetOptions = {
+  // The id is used to choose which display set selector to apply here
   id: string;
+  // An offset to allow display secondary series, for example
+  // to display the second matching series (displaySetIndex==1)
+  // This cannot easily be done with the matching rules directly.
+  displaySetIndex?: number;
+  // The options to apply to the display set.
   options?: Record<string, unknown>;
 };
 
@@ -92,7 +108,6 @@ type ProtocolStage = {
   id: string;
   name: string;
   viewportStructure: ViewportStructure;
-  displaySets: DisplaySet[];
   viewports: Viewport[];
   createdDate?: string;
 };
@@ -100,6 +115,8 @@ type ProtocolStage = {
 type Protocol = {
   // Mandatory
   id: string;
+  // Selects which display sets are given a specific name.
+  displaySetSelectors: Record<string, DisplaySetSelector>;
   stages: ProtocolStage[];
   // Optional
   locked?: boolean;
@@ -129,7 +146,7 @@ export type {
   Protocol,
   ProtocolStage,
   Viewport,
-  DisplaySet,
+  DisplaySetSelector,
   ViewportStructure,
   ViewportLayoutOptions,
   DisplaySetOptions,