feat: stack scroll out of bounds event

common/reviews/api/core.api.md

@@ -879,6 +879,8 @@ export enum EVENTS {
     // (undocumented)
     STACK_NEW_IMAGE = "CORNERSTONE_STACK_NEW_IMAGE",
     // (undocumented)
+    STACK_SCROLL_OUT_OF_BOUNDS = "STACK_SCROLL_OUT_OF_BOUNDS",
+    // (undocumented)
     STACK_VIEWPORT_NEW_STACK = "CORNERSTONE_STACK_VIEWPORT_NEW_STACK",
     // (undocumented)
     STACK_VIEWPORT_SCROLL = "CORNERSTONE_STACK_VIEWPORT_SCROLL",
@@ -956,6 +958,8 @@ declare namespace EventTypes {
         StackViewportNewStackEventDetail,
         StackViewportScrollEvent,
         StackViewportScrollEventDetail,
+        StackScrollOutOfBoundsEvent,
+        StackScrollOutOfBoundsEventDetail,
         CameraResetEvent,
         CameraResetEventDetail
     }
@@ -3091,6 +3095,15 @@ type StackNewImageEventDetail = {
     renderingEngineId: string;
 };
 
+// @public (undocumented)
+type StackScrollOutOfBoundsEvent = CustomEvent_2<StackScrollOutOfBoundsEventDetail>;
+
+// @public (undocumented)
+type StackScrollOutOfBoundsEventDetail = {
+    imageIdIndex: number;
+    direction: number;
+};
+
 // @public (undocumented)
 export class StackViewport extends Viewport implements StackViewport, IImagesLoader {
     constructor(props: ViewportInput);

packages/core/src/enums/Events.ts

@@ -207,6 +207,11 @@ enum Events {
    */
   STACK_VIEWPORT_SCROLL = 'CORNERSTONE_STACK_VIEWPORT_SCROLL',
 
+  /**
+   * Triggers when the scroll function is called with a delta that is out of bounds in the stack viewport.
+   */
+  STACK_SCROLL_OUT_OF_BOUNDS = 'STACK_SCROLL_OUT_OF_BOUNDS',
+
   /**
    * Triggers on the eventTarget when a new geometry is added to the geometry cache
    */

packages/core/src/types/EventTypes.ts

@@ -310,6 +310,16 @@ type StackViewportScrollEventDetail = {
   direction: number;
 };
 
+/**
+ * Stack Scroll out of bounds event detail
+ */
+type StackScrollOutOfBoundsEventDetail = {
+  /** the current imageId index in the stack that we just scroll to */
+  imageIdIndex: number;
+  /** direction of the scroll */
+  direction: number;
+};
+
 /**
  * CameraModified Event type
  */
@@ -431,6 +441,9 @@ type StackViewportNewStackEvent =
 
 type StackViewportScrollEvent = CustomEventType<StackViewportScrollEventDetail>;
 
+type StackScrollOutOfBoundsEvent =
+  CustomEventType<StackScrollOutOfBoundsEventDetail>;
+
 export type {
   CameraModifiedEventDetail,
   CameraModifiedEvent,
@@ -478,6 +491,8 @@ export type {
   StackViewportNewStackEventDetail,
   StackViewportScrollEvent,
   StackViewportScrollEventDetail,
+  StackScrollOutOfBoundsEvent,
+  StackScrollOutOfBoundsEventDetail,
   CameraResetEvent,
   CameraResetEventDetail,
 };

packages/tools/examples/stackManipulationTools/index.ts

@@ -1,11 +1,17 @@
-import { RenderingEngine, Types, Enums } from '@cornerstonejs/core';
+import {
+  eventTarget,
+  RenderingEngine,
+  Types,
+  Enums,
+} from '@cornerstonejs/core';
 import {
   initDemo,
   createImageIdsAndCacheMetaData,
   setTitleAndDescription,
   addDropdownToToolbar,
 } from '../../../../utils/demo/helpers';
 import * as cornerstoneTools from '@cornerstonejs/tools';
+import { StackScrollOutOfBoundsEvent } from 'core/src/types/EventTypes';
 
 // This is for debugging purposes
 console.warn(
@@ -16,6 +22,7 @@ const {
   PanTool,
   WindowLevelTool,
   StackScrollMouseWheelTool,
+  StackScrollTool,
   ZoomTool,
   PlanarRotateTool,
   ToolGroupManager,
@@ -26,7 +33,11 @@ const { ViewportType } = Enums;
 const { MouseBindings } = csToolsEnums;
 
 const toolGroupId = 'STACK_TOOL_GROUP_ID';
-const leftClickTools = [WindowLevelTool.toolName, PlanarRotateTool.toolName];
+const leftClickTools = [
+  WindowLevelTool.toolName,
+  PlanarRotateTool.toolName,
+  StackScrollTool.toolName,
+];
 const defaultLeftClickTool = leftClickTools[0];
 let currentLeftClickTool = leftClickTools[0];
 
@@ -77,6 +88,46 @@ addDropdownToToolbar({
   },
 });
 
+const lastEvents = [];
+const lastEventsDiv = document.createElement('div');
+
+content.appendChild(lastEventsDiv);
+
+function updateLastEvents(number, eventName, detail) {
+  if (lastEvents.length > 4) {
+    lastEvents.pop();
+  }
+
+  lastEvents.unshift({ number, eventName, detail });
+
+  // Display
+  lastEventsDiv.innerHTML = '';
+
+  lastEvents.forEach((le) => {
+    const element = document.createElement('p');
+
+    element.style.border = '1px solid black';
+    element.innerText = le.number + ' ' + le.eventName + '\n\n' + le.detail;
+
+    lastEventsDiv.appendChild(element);
+  });
+}
+
+let eventNumber = 1;
+
+const { STACK_SCROLL_OUT_OF_BOUNDS } = Enums.Events;
+
+eventTarget.addEventListener(STACK_SCROLL_OUT_OF_BOUNDS, ((
+  evt: StackScrollOutOfBoundsEvent
+) => {
+  updateLastEvents(
+    eventNumber,
+    STACK_SCROLL_OUT_OF_BOUNDS,
+    JSON.stringify(evt.detail)
+  );
+  eventNumber++;
+}) as EventListener);
+
 /**
  * Runs the demo
  */
@@ -88,6 +139,7 @@ async function run() {
   cornerstoneTools.addTool(PanTool);
   cornerstoneTools.addTool(WindowLevelTool);
   cornerstoneTools.addTool(StackScrollMouseWheelTool);
+  cornerstoneTools.addTool(StackScrollTool);
   cornerstoneTools.addTool(ZoomTool);
   cornerstoneTools.addTool(PlanarRotateTool);
 
@@ -100,6 +152,7 @@ async function run() {
   toolGroup.addTool(PanTool.toolName);
   toolGroup.addTool(ZoomTool.toolName);
   toolGroup.addTool(StackScrollMouseWheelTool.toolName, { loop: false });
+  toolGroup.addTool(StackScrollTool.toolName, { loop: false });
   toolGroup.addTool(PlanarRotateTool.toolName);
 
   // Set the initial state of the tools, here all tools are active and bound to

packages/tools/src/utilities/scroll.ts

@@ -41,6 +41,24 @@ export default function scroll(
   if (viewport instanceof VolumeViewport) {
     scrollVolume(viewport, volumeId, delta, scrollSlabs);
   } else {
+    const imageIdIndex = viewport.getCurrentImageIdIndex();
+
+    if (
+      imageIdIndex + delta >
+        (viewport as Types.IStackViewport).getImageIds().length - 1 ||
+      imageIdIndex + delta < 0
+    ) {
+      const eventData: Types.EventTypes.StackScrollOutOfBoundsEventDetail = {
+        imageIdIndex,
+        direction: delta,
+      };
+      csUtils.triggerEvent(
+        eventTarget,
+        EVENTS.STACK_SCROLL_OUT_OF_BOUNDS,
+        eventData
+      );