@cornerstonejs/metadata 5.13.2 → 5.14.0

package/dist/esm/displayset/displayset.test.js

@@ -1,13 +1,16 @@
 import { describe, expect, it } from '@jest/globals';
 import { buildSeriesInfo } from './buildSeriesInfo.js';
 import { createDisplaySetFromGroup } from './createDisplaySetFromGroup.js';
-import { defaultDisplaySetSplitRules } from './defaultDisplaySetSplitRules.js';
-import { groupInstancesBySplitRules } from './groupInstancesBySplitRules.js';
+import { compiledDisplaySetRules } from './compiledDisplaySetRules.js';
+import { groupInstancesBySplitRules, orderInstancesForRule, } from './groupInstancesBySplitRules.js';
 import { ImageStackDisplaySet } from './ImageStackDisplaySet.js';
 import { isVideoInstance } from './isVideoInstance.js';
 import { resolveInstances } from './resolveInstances.js';
 import { splitImageIdsBySplitRules } from './splitImageIdsBySplitRules.js';
-import { getPreferredViewportType } from './viewportTypes.js';
+const ruleSet = (...rules) => Object.fromEntries(rules.map(({ id, ...rule }, index) => [
+    id,
+    { ...rule, priority: index + 1 },
+]));
 describe('displayset split utilities', () => {
     const instances = [
         {
@@ -34,19 +37,24 @@ describe('displayset split utilities', () => {
         const resolved = resolveInstances(['wadors:2', 'wadors:missing', 'wadors:1'], getNaturalizedInstance);
         expect(resolved.map((i) => i.imageId)).toEqual(['wadors:2', 'wadors:1']);
     });
-    it('default rules group multi-slice CT as volume (MPR) preferred', () => {
+    it('rejects an invalid rule set also when no image id resolves', () => {
+        expect(() => splitImageIdsBySplitRules(['wadors:missing'], {
+            getNaturalizedInstance,
+            splitRules: { bad: { priority: 'high' } },
+        })).toThrow(/"bad".*priority/);
+    });
+    it('default rules group multi-slice CT as one image stack, with no handler', () => {
         const groups = splitImageIdsBySplitRules(instances.map((i) => i.imageId), {
             getNaturalizedInstance: (id) => instances.find((i) => i.imageId === id),
-            splitRules: defaultDisplaySetSplitRules,
+            splitRules: compiledDisplaySetRules,
         });
         expect(groups).toHaveLength(1);
         expect(groups[0].matchedRule.id).toBe('volume3d');
         const displaySet = createDisplaySetFromGroup(groups[0]);
-        expect(displaySet.viewportTypes[0]).toBe('volume');
-        expect(displaySet.viewportTypes).toContain('volume3d');
-        expect(displaySet.preferredViewportType).toBe('volume');
+        expect(displaySet).toBeInstanceOf(ImageStackDisplaySet);
+        expect(displaySet.handler).toBeUndefined();
     });
-    it('video rule uses video viewportTypes', () => {
+    it('video rule gives the video handler', () => {
         const videoInstance = {
             imageId: 'wadors:video',
             SOPClassUID: '1.2.840.10008.5.1.4.1.1.77.1.4.1',
@@ -54,15 +62,14 @@ describe('displayset split utilities', () => {
         };
         const groups = splitImageIdsBySplitRules(['wadors:video'], {
             getNaturalizedInstance: () => videoInstance,
-            splitRules: defaultDisplaySetSplitRules,
+            splitRules: compiledDisplaySetRules,
         });
         expect(groups[0].matchedRule.id).toBe('video');
         const displaySet = createDisplaySetFromGroup(groups[0]);
-        expect(displaySet.viewportTypes).toEqual(['video']);
-        expect(getPreferredViewportType(displaySet.viewportTypes)).toBe('video');
+        expect(displaySet.handler).toBe('video');
         expect(displaySet.instances[0]?.imageId).toBe('wadors:video');
     });
-    it('ecg rule uses ecg viewportTypes', () => {
+    it('ecg rule gives the ecg handler', () => {
         const ecgInstance = {
             imageId: 'wadors:ecg',
             SOPClassUID: '1.2.840.10008.5.1.4.1.1.9.1.1',
@@ -70,57 +77,16 @@ describe('displayset split utilities', () => {
         };
         const groups = splitImageIdsBySplitRules(['wadors:ecg'], {
             getNaturalizedInstance: () => ecgInstance,
-            splitRules: defaultDisplaySetSplitRules,
+            splitRules: compiledDisplaySetRules,
         });
         expect(groups[0].matchedRule.id).toBe('ecg');
-        expect(createDisplaySetFromGroup(groups[0]).viewportTypes[0]).toBe('ecg');
-    });
-    it('splits MR mixed B-value series', () => {
-        const mrInstances = [
-            {
-                imageId: 'wadors:a',
-                Modality: 'MR',
-                SOPClassUID: '1.2.840.10008.5.1.4.1.1.4',
-                Rows: 256,
-                SeriesInstanceUID: 'series-mr',
-                DiffusionBValue: 800,
-            },
-            {
-                imageId: 'wadors:b',
-                Modality: 'MR',
-                SOPClassUID: '1.2.840.10008.5.1.4.1.1.4',
-                Rows: 256,
-                SeriesInstanceUID: 'series-mr',
-            },
-        ];
-        const groups = splitImageIdsBySplitRules(mrInstances.map((i) => i.imageId), {
-            getNaturalizedInstance: (id) => mrInstances.find((i) => i.imageId === id),
-            splitRules: defaultDisplaySetSplitRules,
-        });
-        expect(groups).toHaveLength(2);
+        expect(createDisplaySetFromGroup(groups[0]).handler).toBe('ecg');
     });
     it('ImageStackDisplaySet exposes underlying and frame ids', () => {
         const displaySet = ImageStackDisplaySet.fromInstances(instances, {
             displaySetId: 'uid-1',
-            viewportTypes: ['stack', 'volume', 'volume3d'],
         });
         expect(displaySet.underlyingImageIds.length).toBe(2);
-        expect(displaySet.viewportTypes[0]).toBe('stack');
-        expect(displaySet.preferredViewportType).toBe('stack');
-    });
-    it('groups by default image rule into a single group', () => {
-        const singleInstance = [instances[0]];
-        const rules = [
-            {
-                id: 'defaultImageRule',
-                viewportTypes: ['stack'],
-                matches: (instance) => instance.SOPClassUID === '1.2.840.10008.5.1.4.1.1.2' &&
-                    !!instance.Rows,
-            },
-        ];
-        const groups = groupInstancesBySplitRules(singleInstance, rules);
-        expect(groups).toHaveLength(1);
-        expect(groups[0].instances).toHaveLength(1);
     });
     it('spreads matched-rule customAttributes flat onto the display set', () => {
         const multiFrameInstances = [
@@ -129,7 +95,7 @@ describe('displayset split utilities', () => {
                 Modality: 'XA',
                 SOPClassUID: '1.2.840.10008.5.1.4.1.1.12.1',
                 Rows: 512,
-                NumberOfFrames: 30,
+                NumberOfFrames: '30',
                 SliceLocation: 0,
                 SeriesInstanceUID: 'series-mf',
                 InstanceNumber: 1,
@@ -137,36 +103,16 @@ describe('displayset split utilities', () => {
         ];
         const groups = splitImageIdsBySplitRules(['wadors:mf'], {
             getNaturalizedInstance: () => multiFrameInstances[0],
-            splitRules: defaultDisplaySetSplitRules,
+            splitRules: compiledDisplaySetRules,
         });
         expect(groups[0].matchedRule.id).toBe('multiFrame');
         const displaySet = createDisplaySetFromGroup(groups[0], { splitNumber: 2 });
         expect(displaySet.isClip).toBe(true);
         expect(displaySet.numImageFrames).toBe(30);
         expect(displaySet.splitNumber).toBe(2);
-        expect(displaySet.viewportTypes).toEqual(['stack']);
-    });
-    it('coerces a string NumberOfFrames to a numeric numImageFrames', () => {
-        const multiFrameInstances = [
-            {
-                imageId: 'wadors:mf-str',
-                Modality: 'XA',
-                SOPClassUID: '1.2.840.10008.5.1.4.1.1.12.1',
-                Rows: 512,
-                NumberOfFrames: '30',
-                SliceLocation: 0,
-                SeriesInstanceUID: 'series-mf-str',
-                InstanceNumber: 1,
-            },
-        ];
-        const groups = splitImageIdsBySplitRules(['wadors:mf-str'], {
-            getNaturalizedInstance: () => multiFrameInstances[0],
-            splitRules: defaultDisplaySetSplitRules,
-        });
-        expect(groups[0].matchedRule.id).toBe('multiFrame');
-        const displaySet = createDisplaySetFromGroup(groups[0]);
-        expect(displaySet.numImageFrames).toBe(30);
-        expect(typeof displaySet.numImageFrames).toBe('number');
+        expect(displaySet.sopClassUids).toEqual([
+            multiFrameInstances[0].SOPClassUID,
+        ]);
     });
     it('classifies an MPEG2 transfer syntax instance as video', () => {
         const mpeg2Instance = {
@@ -181,7 +127,7 @@ describe('displayset split utilities', () => {
         expect(() => buildSeriesInfo([])).not.toThrow();
         const seriesInfo = buildSeriesInfo([]);
         expect(seriesInfo.NumberOfSeriesRelatedInstances).toBe(0);
-        expect(groupInstancesBySplitRules([], defaultDisplaySetSplitRules)).toEqual([]);
+        expect(groupInstancesBySplitRules([], compiledDisplaySetRules)).toEqual([]);
     });
     it('does not let customAttributes clobber resolved data fields', () => {
         const stackInstances = [
@@ -197,7 +143,6 @@ describe('displayset split utilities', () => {
             instances: stackInstances,
             matchedRule: {
                 id: 'reserved-clobber',
-                viewportTypes: ['stack'],
                 customAttributes: () => ({
                     imageIds: ['evil-frame'],
                     underlyingImageIds: ['evil-underlying'],
@@ -216,6 +161,76 @@ describe('displayset split utilities', () => {
         expect(displaySet.displaySetId).toBe('good-uid');
         expect(displaySet.customFlag).toBe(true);
     });
+    it('records the split identity, and attributes cannot rename it', () => {
+        const group = {
+            instances: [
+                {
+                    imageId: 'wadors:identity',
+                    SOPClassUID: '1.2.840.10008.5.1.4.1.1.2',
+                    Rows: 512,
+                    SeriesInstanceUID: 'series-identity',
+                    InstanceNumber: 1,
+                },
+            ],
+            matchedRule: {
+                id: 'mgLegacy',
+                groupId: 'mammo',
+                customAttributes: () => ({
+                    splitKey: 'other',
+                    splitRuleId: 'other',
+                    splitGroupId: 'other',
+                }),
+            },
+            splitKey: '["mgLegacy","series-identity"]',
+        };
+        const displaySet = createDisplaySetFromGroup(group);
+        expect(displaySet.splitKey).toBe('["mgLegacy","series-identity"]');
+        expect(displaySet.splitRuleId).toBe('mgLegacy');
+        expect(displaySet.splitGroupId).toBe('mammo');
+    });
+    it('does not let a __proto__ custom attribute replace the prototype', () => {
+        const group = {
+            instances: [
+                {
+                    imageId: 'wadors:proto',
+                    SOPClassUID: '1.2.840.10008.5.1.4.1.1.2',
+                    Rows: 512,
+                    SeriesInstanceUID: 'series-proto',
+                    InstanceNumber: 1,
+                },
+            ],
+            matchedRule: {
+                id: 'proto',
+                customAttributes: () => JSON.parse('{"__proto__": {"x": 1}, "y": 2}'),
+            },
+        };
+        const displaySet = createDisplaySetFromGroup(group);
+        expect(displaySet).toBeInstanceOf(ImageStackDisplaySet);
+        expect(displaySet.x).toBeUndefined();
+        expect(displaySet.y).toBe(2);
+    });
+    it('does not let customAttributes change isDisplayable or the handler', () => {
+        const displaySet = createDisplaySetFromGroup({
+            instances: [
+                {
+                    imageId: 'wadors:pr',
+                    SOPClassUID: '1.2.840.10008.5.1.4.1.1.11.1',
+                    SeriesInstanceUID: 'series-pr',
+                },
+            ],
+            matchedRule: {
+                id: 'unsupported',
+                handler: 'unsupported',
+                customAttributes: () => ({ isDisplayable: true, handler: 'image' }),
+            },
+        });
+        expect([displaySet.isDisplayable, displaySet.handler]).toEqual([
+            false,
+            'unsupported',
+        ]);
+        expect(displaySet.imageIds).toEqual([]);
+        expect(displaySet.underlyingImageIds).toEqual(['wadors:pr']);
+    });
     it('derives unique displaySetIds for splits of one series', () => {
         const seriesUID = 'series-split';
         const makeGroup = (imageId) => ({
@@ -227,7 +242,7 @@ describe('displayset split utilities', () => {
                     SeriesInstanceUID: seriesUID,
                 },
             ],
-            matchedRule: { id: 'split', viewportTypes: ['stack'] },
+            matchedRule: { id: 'split' },
         });
         const ds0 = createDisplaySetFromGroup(makeGroup('wadors:s0'), {
             splitNumber: 0,
@@ -244,18 +259,15 @@ describe('displayset split utilities', () => {
             { imageId: 'a', Modality: 'XA' },
             { imageId: 'b', Modality: 'NM' },
         ];
-        const rules = [
-            {
-                id: 'ruleA',
-                matches: (i) => i.Modality === 'XA',
-                groupBy: [() => 'same'],
-            },
-            {
-                id: 'ruleB',
-                matches: (i) => i.Modality === 'NM',
-                groupBy: [() => 'same'],
-            },
-        ];
+        const rules = ruleSet({
+            id: 'ruleA',
+            matches: (i) => i.Modality === 'XA',
+            groupBy: [() => 'same'],
+        }, {
+            id: 'ruleB',
+            matches: (i) => i.Modality === 'NM',
+            groupBy: [() => 'same'],
+        });
         const groups = groupInstancesBySplitRules(insts, rules);
         expect(groups).toHaveLength(2);
         expect(new Set(groups.map((g) => g.matchedRule.id))).toEqual(new Set(['ruleA', 'ruleB']));
@@ -280,37 +292,12 @@ describe('displayset split utilities', () => {
         ];
         const options = {
             getNaturalizedInstance: (id) => mr.find((i) => i.imageId === id),
-            splitRules: defaultDisplaySetSplitRules,
+            splitRules: compiledDisplaySetRules,
         };
         const forward = splitImageIdsBySplitRules(['a', 'b'], options);
         const reverse = splitImageIdsBySplitRules(['b', 'a'], options);
         expect(forward.map((g) => g.splitKey)).toEqual(reverse.map((g) => g.splitKey));
     });
-    it('series hook splits a mixed-b-value DWI series into two display sets', () => {
-        const mixed = [
-            {
-                imageId: 'b800',
-                Modality: 'MR',
-                SOPClassUID: '1.2.840.10008.5.1.4.1.1.4',
-                Rows: 256,
-                SeriesInstanceUID: 'dwi',
-                DiffusionBValue: 800,
-            },
-            {
-                imageId: 'noB',
-                Modality: 'MR',
-                SOPClassUID: '1.2.840.10008.5.1.4.1.1.4',
-                Rows: 256,
-                SeriesInstanceUID: 'dwi',
-            },
-        ];
-        const groups = splitImageIdsBySplitRules(['b800', 'noB'], {
-            getNaturalizedInstance: (id) => mixed.find((i) => i.imageId === id),
-            splitRules: defaultDisplaySetSplitRules,
-        });
-        expect(groups).toHaveLength(2);
-        expect(groups.every((g) => g.matchedRule.id === 'mixedDimensionalityBValue')).toBe(true);
-    });
     it('series hook leaves a non-mixed DWI series as one volume display set', () => {
         const allBValue = [
             {
@@ -332,7 +319,7 @@ describe('displayset split utilities', () => {
         ];
         const groups = splitImageIdsBySplitRules(['b0', 'b1000'], {
             getNaturalizedInstance: (id) => allBValue.find((i) => i.imageId === id),
-            splitRules: defaultDisplaySetSplitRules,
+            splitRules: compiledDisplaySetRules,
         });
         expect(groups).toHaveLength(1);
         expect(groups[0].matchedRule.id).toBe('volume3d');
@@ -342,16 +329,321 @@ describe('displayset split utilities', () => {
             { imageId: 'a', Modality: 'CT' },
             { imageId: 'b', Modality: 'SR' },
         ];
-        const rules = [
-            {
-                id: 'ct',
-                matches: (i) => i.Modality === 'CT',
-                groupBy: ['imageId'],
-            },
-        ];
+        const rules = ruleSet({
+            id: 'ct',
+            matches: (i) => i.Modality === 'CT',
+            groupBy: ['imageId'],
+        });
         const unmatched = [];
         const groups = groupInstancesBySplitRules(insts, rules, (i) => unmatched.push(i.imageId));
         expect(unmatched).toEqual(['b']);
         expect(groups).toHaveLength(1);
     });
 });
+describe('split key stability', () => {
+    const ct = (imageId, InstanceNumber) => ({
+        imageId,
+        Modality: 'CT',
+        SOPClassUID: '1.2.840.10008.5.1.4.1.1.2',
+        Rows: 512,
+        SeriesInstanceUID: 'series-1',
+        SOPInstanceUID: `sop-${imageId}`,
+        InstanceNumber,
+    });
+    const ctRule = {
+        id: 'ct',
+        matches: (i) => i.Modality === 'CT',
+        groupBy: ['SeriesInstanceUID', 'InstanceNumber'],
+    };
+    it('keys off the rule id, so inserting a rule leaves other rules keys unchanged', () => {
+        const instances = [ct('a', 1), ct('b', 2)];
+        const before = groupInstancesBySplitRules(instances, {
+            ct: { ...ctRule, priority: 1 },
+        });
+        const after = groupInstancesBySplitRules(instances, {
+            ct: { ...ctRule, priority: 1 },
+            insertedAhead: {
+                priority: -1,
+                matches: (i) => i.InstanceNumber === 2,
+            },
+        });
+        expect(after.map((g) => g.matchedRule.id)).toEqual(['insertedAhead', 'ct']);
+        const ctKey = (groups) => groups.find((g) => g.matchedRule.id === 'ct')?.splitKey;
+        expect(ctKey(after)).toBe(ctKey(before));
+    });
+    it('keys a group by the rule id taken from the rule set key', () => {
+        const groups = groupInstancesBySplitRules([ct('a', 1)], {
+            byImage: { priority: 1, groupBy: ['imageId'] },
+        });
+        expect(groups[0].matchedRule.id).toBe('byImage');
+        expect(groups[0].splitKey).toBe(JSON.stringify(['byImage', 'a']));
+    });
+    it('orders groups by rule position, then by key numerically', () => {
+        const instances = [ct('j', 10), ct('b', 2), ct('a', 1)];
+        const groups = groupInstancesBySplitRules(instances, ruleSet(ctRule));
+        expect(groups.map((g) => g.instances[0].imageId)).toEqual(['a', 'b', 'j']);
+    });
+    it('orders keys differing only in zero padding deterministically', () => {
+        const padded = (imageId, AcquisitionNumber) => ({
+            imageId,
+            Modality: 'CT',
+            SeriesInstanceUID: 'series-1',
+            SOPInstanceUID: `sop-${imageId}`,
+            AcquisitionNumber,
+        });
+        const rule = {
+            id: 'padded',
+            matches: () => true,
+            groupBy: ['AcquisitionNumber'],
+        };
+        const forward = groupInstancesBySplitRules([padded('a', '01'), padded('b', '1')], ruleSet(rule));
+        const reverse = groupInstancesBySplitRules([padded('b', '1'), padded('a', '01')], ruleSet(rule));
+        expect(forward).toHaveLength(2);
+        expect(forward.map((g) => g.instances[0].imageId)).toEqual(reverse.map((g) => g.instances[0].imageId));
+        expect(forward.map((g) => g.splitKey)).toEqual(reverse.map((g) => g.splitKey));
+    });
+});
+describe('compareInstances - rule-declared instance order', () => {
+    const slice = (imageId, SliceLocation, InstanceNumber) => ({
+        imageId,
+        Modality: 'CT',
+        SOPClassUID: '1.2.840.10008.5.1.4.1.1.2',
+        Rows: 512,
+        SeriesInstanceUID: 'ct-series',
+        SOPInstanceUID: `sop-${imageId}`,
+        SliceLocation,
+        InstanceNumber,
+    });
+    const reconstructed = [
+        slice('top', 30, 2),
+        slice('middle', 20, 3),
+        slice('bottom', 10, 1),
+    ];
+    const spatialRule = {
+        id: 'spatial',
+        matches: () => true,
+        compareInstances: (a, b) => a.SliceLocation - b.SliceLocation,
+    };
+    it('orders a group by the rule comparator instead of acquisition order', () => {
+        const groups = groupInstancesBySplitRules(reconstructed, ruleSet(spatialRule));
+        expect(groups[0].instances.map((i) => i.imageId)).toEqual([
+            'bottom',
+            'middle',
+            'top',
+        ]);
+    });
+    it('defaults to acquisition order when the rule declares no comparator', () => {
+        const groups = groupInstancesBySplitRules(reconstructed, ruleSet({ id: 'default', matches: () => true }));
+        expect(groups[0].instances.map((i) => i.imageId)).toEqual([
+            'bottom',
+            'top',
+            'middle',
+        ]);
+    });
+    it('reads the rule series facts through the comparator context', () => {
+        const groups = groupInstancesBySplitRules([...reconstructed].reverse(), ruleSet({
+            id: 'directional',
+            matches: () => true,
+            series: () => ({ descending: true }),
+            compareInstances: (a, b, context) => (context.series.descending ? -1 : 1) *
+                (a.SliceLocation - b.SliceLocation),
+        }));
+        expect(groups[0].instances.map((i) => i.imageId)).toEqual([
+            'top',
+            'middle',
+            'bottom',
+        ]);
+    });
+    it('breaks ties from an incomplete comparator by acquisition order', () => {
+        const sameLocation = [
+            slice('a', 10, 1),
+            slice('b', 10, 2),
+            slice('c', 10, 3),
+        ];
+        const forward = groupInstancesBySplitRules(sameLocation, ruleSet(spatialRule));
+        const reversed = groupInstancesBySplitRules([...sameLocation].reverse(), ruleSet(spatialRule));
+        expect(forward[0].instances.map((i) => i.imageId)).toEqual(['a', 'b', 'c']);
+        expect(reversed[0].instances.map((i) => i.imageId)).toEqual([
+            'a',
+            'b',
+            'c',
+        ]);
+    });
+    it('falls back to acquisition order when the comparator returns NaN', () => {
+        const partial = [
+            slice('second', 20, 2),
+            { ...slice('first', 10, 1), SliceLocation: undefined },
+        ];
+        expect(groupInstancesBySplitRules(partial, ruleSet(spatialRule))[0].instances.map((i) => i.imageId)).toEqual(['first', 'second']);
+        expect(groupInstancesBySplitRules([...partial].reverse(), ruleSet(spatialRule))[0].instances.map((i) => i.imageId)).toEqual(['first', 'second']);
+    });
+});
+describe('host-supplied instance ordering', () => {
+    const slice = (imageId, SliceLocation, InstanceNumber) => ({
+        imageId,
+        Modality: 'CT',
+        SOPClassUID: '1.2.840.10008.5.1.4.1.1.2',
+        Rows: 512,
+        SeriesInstanceUID: 'ct-series',
+        SOPInstanceUID: `sop-${imageId}`,
+        SliceLocation,
+        InstanceNumber,
+    });
+    const instances = [slice('a', 10, 3), slice('b', 20, 1), slice('c', 30, 2)];
+    const plainRule = { id: 'plain', matches: () => true };
+    const byPosition = (list) => [...list].sort((a, b) => a.SliceLocation - b.SliceLocation);
+    const byPositionDescending = (list) => [...list].sort((a, b) => b.SliceLocation - a.SliceLocation);
+    const ids = (groups) => groups[0].instances.map((i) => i.imageId);
+    it('applies a host base sort to every rule', () => {
+        const groups = groupInstancesBySplitRules(instances, ruleSet(plainRule), undefined, { sortInstances: byPosition });
+        expect(ids(groups)).toEqual(['a', 'b', 'c']);
+    });
+    it('tells the base sort which rule it is ordering for', () => {
+        const seen = [];
+        groupInstancesBySplitRules(instances, ruleSet(plainRule), undefined, {
+            sortInstances: (list, context) => {
+                seen.push(context.matchedRule.id ?? '');
+                return list;
+            },
+        });
+        expect(seen).toEqual(['plain']);
+    });
+    it('lets a rule comparator override the host base sort', () => {
+        const groups = groupInstancesBySplitRules(instances, ruleSet({
+            id: 'descending',
+            matches: () => true,
+            compareInstances: (a, b) => b.SliceLocation - a.SliceLocation,
+        }), undefined, { sortInstances: byPosition });
+        expect(ids(groups)).toEqual(['c', 'b', 'a']);
+    });
+    it('falls through to the base order when a comparator returns 0', () => {
+        const groups = groupInstancesBySplitRules(instances, ruleSet({
+            id: 'aFirst',
+            matches: () => true,
+            compareInstances: (x, y) => {
+                if (x.imageId === y.imageId) {
+                    return 0;
+                }
+                if (x.imageId === 'a') {
+                    return -1;
+                }
+                if (y.imageId === 'a') {
+                    return 1;
+                }
+                return 0;
+            },
+        }), undefined, { sortInstances: byPositionDescending });
+        expect(ids(groups)).toEqual(['a', 'c', 'b']);
+    });
+    it('consults the host comparator after the rule declines', () => {
+        const groups = groupInstancesBySplitRules(instances, ruleSet({
+            id: 'noOpinion',
+            matches: () => true,
+            compareInstances: () => 0,
+        }), undefined, {
+            compareInstances: (a, b) => a.SliceLocation - b.SliceLocation,
+        });
+        expect(ids(groups)).toEqual(['a', 'b', 'c']);
+    });
+    it('prefers the rule comparator over the host comparator', () => {
+        const groups = groupInstancesBySplitRules(instances, ruleSet({
+            id: 'ruleWins',
+            matches: () => true,
+            compareInstances: (a, b) => b.SliceLocation - a.SliceLocation,
+        }), undefined, {
+            compareInstances: (a, b) => a.SliceLocation - b.SliceLocation,
+        });
+        expect(ids(groups)).toEqual(['c', 'b', 'a']);
+    });
+    it('treats a NaN comparator result as no opinion', () => {
+        const groups = groupInstancesBySplitRules(instances, ruleSet({
+            id: 'missingTag',
+            matches: () => true,
+            compareInstances: (a, b) => a.Missing - b.Missing,
+        }), undefined, { sortInstances: byPosition });
+        expect(ids(groups)).toEqual(['a', 'b', 'c']);
+    });
+    it('orderInstancesForRule reproduces the engine order outside a split', () => {
+        const options = { sortInstances: byPosition };
+        const rule = {
+            id: 'descending',
+            matches: () => true,
+            compareInstances: (a, b) => b.SliceLocation - a.SliceLocation,
+        };
+        const fromEngine = ids(groupInstancesBySplitRules(instances, ruleSet(rule), undefined, options));
+        const standalone = orderInstancesForRule(instances, rule, options).map((i) => i.imageId);
+        expect(standalone).toEqual(fromEngine);
+    });
+});
+describe('InstanceGroup.series - the facts of the whole split', () => {
+    const mr = (imageId, InstanceNumber, SliceLocation, DiffusionBValue) => ({
+        imageId,
+        Modality: 'MR',
+        SeriesInstanceUID: 'dwi',
+        SOPInstanceUID: `sop-${imageId}`,
+        InstanceNumber,
+        SliceLocation,
+        ...(DiffusionBValue === undefined ? {} : { DiffusionBValue }),
+    });
+    const dwi = [
+        mr('b1', 1, 10, 800),
+        mr('b2', 2, 20, 800),
+        mr('n1', 3, 10),
+        mr('n2', 4, 20),
+    ];
+    const mixedBValue = ({ instances }) => {
+        const withB = instances.filter((i) => i.DiffusionBValue !== undefined);
+        return {
+            mixed: withB.length > 0 && withB.length < instances.length,
+        };
+    };
+    const dwiRule = {
+        id: 'dwi',
+        series: mixedBValue,
+        groupBy: [
+            'SeriesInstanceUID',
+            (instance) => instance.DiffusionBValue === undefined,
+        ],
+        compareInstances: (a, b, context) => (context.series.mixed ? -1 : 1) *
+            (a.SliceLocation - b.SliceLocation),
+    };
+    const ids = (list) => list.map((i) => i.imageId);
+    it('gives every group the series facts of all instances in the split', () => {
+        const groups = groupInstancesBySplitRules(dwi, ruleSet(dwiRule));
+        expect(groups.map((g) => ids(g.instances))).toEqual([
+            ['b2', 'b1'],
+            ['n2', 'n1'],
+        ]);
+        for (const group of groups) {
+            expect(mixedBValue({ instances: group.instances })).toEqual({
+                mixed: false,
+            });
+            expect(group.series).toEqual({ mixed: true });
+        }
+    });
+    it('gives a rule with no series hook an empty facts object', () => {
+        const groups = groupInstancesBySplitRules(dwi, ruleSet({ id: 'plain', groupBy: ['SeriesInstanceUID'] }));
+        expect(groups[0].series).toEqual({});
+    });
+    it('orderInstancesForRule uses options.series instead of recomputing the facts', () => {
+        const [firstHalf] = groupInstancesBySplitRules(dwi, ruleSet(dwiRule));
+        expect(ids(orderInstancesForRule(firstHalf.instances, dwiRule, {
+            series: firstHalf.series,
+        }))).toEqual(['b2', 'b1']);
+        expect(ids(orderInstancesForRule(firstHalf.instances, dwiRule))).toEqual([
+            'b1',
+            'b2',
+        ]);
+    });
+    it('orderInstancesForRule passes options.series to the host sort too', () => {
+        const seen = [];
+        orderInstancesForRule(dwi, dwiRule, {
+            series: { mixed: 'from the caller' },
+            sortInstances: (list, context) => {
+                seen.push(context.series.mixed);
+                return list;
+            },
+        });
+        expect(seen).toEqual(['from the caller']);
+    });
+});