JavaScript (v3): HealthImaging - Image sets and data frames workflow. (#6345)

Author: cpyle0819

.doc_gen/metadata/medical-imaging_metadata.yaml

@@ -1169,6 +1169,22 @@ medical-imaging_Scenario_ImageSetsAndFrames:
               snippet_tags:
                 - cpp.example_code.medical-imaging.image-sets-workflow.clean_up
                 - cpp.example_code.medical-imaging.image-sets-workflow.empty_data_store
+    JavaScript:
+      versions:
+        - sdk_version: 3
+          github: javascriptv3/example_code/medical-imaging
+          github_note_at_bottom: true
+          excerpts:
+            - description:
+              snippet_files:
+                - javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/index.js
+                - javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/step-1.js
+                - javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/step-2.js
+                - javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/step-3.js
+                - javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/step-4.js
+                - javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/step-5.js
+                - javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/step-6.js
+                - javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/step-7.js
   services:
     medical-imaging:
       {

javascriptv3/.eslintignore

@@ -1 +1,2 @@
-/example_code/reactnative/
+/example_code/reactnative/
+/example_code/medical-imaging/scenarios/health-image-sets/pixel-data-verification

javascriptv3/example_code/libs/scenario/scenario.js

@@ -22,10 +22,10 @@ export class Step {
       console.log(
         `[DEBUG ${new Date().toISOString()}] Handling step: ${
           this.constructor.name
-        }<${this.name}>`,
+        }<${this.name}>`
       );
       console.log(
-        `[DEBUG ${new Date().toISOString()}] State: ${JSON.stringify(state)}`,
+        `[DEBUG ${new Date().toISOString()}] State: ${JSON.stringify(state)}`
       );
     }
   }
@@ -126,7 +126,7 @@ export class ScenarioInput extends Step {
       });
     } else {
       throw new Error(
-        `Error handling ScenarioInput, ${this.options?.type} is not supported.`,
+        `Error handling ScenarioInput, ${this.options?.type} is not supported.`
       );
     }
 
@@ -137,7 +137,7 @@ export class ScenarioInput extends Step {
 export class ScenarioAction extends Step {
   /**
    * @param {string} name
-   * @param {(state: Record<string, any>) => Promise<void>} action
+   * @param {(state: Record<string, any>, options) => Promise<void>} action
    * @param {{ whileConfig: { inputEquals: any, input: ScenarioInput, output: ScenarioOutput }}} [options]
    */
   constructor(name, action, options) {
@@ -153,7 +153,7 @@ export class ScenarioAction extends Step {
   async handle(state, options) {
     const _handle = async () => {
       super.handle(state, options);
-      await this.action(state);
+      await this.action(state, options);
     };
 
     if (!options?.confirmAll && this.options?.whileConfig) {
@@ -180,14 +180,19 @@ export class Scenario {
    */
   state = {};
 
+  /**
+   * @type {(ScenarioOutput | ScenarioInput | ScenarioAction | Scenario)[]}
+   */
+  steps = [];
+
   /**
    * @param {string} name
-   * @param {(ScenarioOutput | ScenarioInput | ScenarioAction)[]} steps
+   * @param {(ScenarioOutput | ScenarioInput | ScenarioAction | null)[]} steps
    * @param {Record<string, any>} initialState
    */
   constructor(name, steps = [], initialState = {}) {
     this.name = name;
-    this.steps = steps;
+    this.steps = steps.filter((s) => !!s);
     this.state = { ...initialState, name };
   }
 
@@ -196,7 +201,11 @@ export class Scenario {
    */
   async run(runConfig) {
     for (const step of this.steps) {
-      await step.handle(this.state, runConfig);
+      if (step instanceof Scenario) {
+        await step.run(runConfig);
+      } else {
+        await step.handle(this.state, runConfig);
+      }
     }
   }
 }

javascriptv3/example_code/medical-imaging/README.md

@@ -62,6 +62,7 @@ Code excerpts that show you how to call individual service functions.
 Code examples that show you how to accomplish a specific task by calling multiple
 functions within the same service.
 
+- [Get started with image sets and image frames](scenarios/health-image-sets/index.js)
 - [Tagging a data store](scenarios/tagging-datastores.js)
 - [Tagging an image set](scenarios/tagging-imagesets.js)
 
@@ -100,6 +101,27 @@ node ./hello.js
 ```
 
 
+#### Get started with image sets and image frames
+
+This example shows you how to import DICOM files and download image frames in HealthImaging.</para>
+ <para>The implementation is structured as a workflow command-line
+ application.
+
+
+- Set up resources for a DICOM import.
+- Import DICOM files into a data store.
+- Retrieve the image set IDs for the import job.
+- Retrieve the image frame IDs for the image sets.
+- Download, decode and verify the image frames.
+- Clean up resources.
+
+<!--custom.scenario_prereqs.medical-imaging_Scenario_ImageSetsAndFrames.start-->
+<!--custom.scenario_prereqs.medical-imaging_Scenario_ImageSetsAndFrames.end-->
+
+
+<!--custom.scenarios.medical-imaging_Scenario_ImageSetsAndFrames.start-->
+<!--custom.scenarios.medical-imaging_Scenario_ImageSetsAndFrames.end-->
+
 #### Tagging a data store
 
 This example shows you how to tag a HealthImaging data store.

javascriptv3/example_code/medical-imaging/package.json

@@ -5,13 +5,16 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@aws-doc-sdk-examples/lib": "^1.0.0",
-    "@aws-sdk/client-medical-imaging": "^3.391.0"
+    "@aws-sdk/client-cloudformation": "3.540.0",
+    "@aws-sdk/client-medical-imaging": "^3.391.0",
+    "@aws-sdk/client-sts": "^3.540.0"
   },
   "scripts": {
+    "test": "vitest run **/*.unit.test.js",
     "integration-test": "vitest run **/*.integration.test.js"
   },
   "type": "module",
   "devDependencies": {
-    "vitest": "^0.25.2"
+    "vitest": "^1.5.0"
   }
 }

javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/.gitignore

@@ -0,0 +1 @@
+*state.json

javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/README.md

@@ -0,0 +1,77 @@
+# Import HealthImaging Image Sets and Download Image Frames using the AWS SDK for JavaScript
+
+## Overview
+
+This workflow shows how to use the AWS SDK for JavaScript to import DICOM files into an AWS HealthImaging data store. It then shows how to download, decode, and verify the image frames created by the DICOM import.
+
+Digital Imaging and Communications in Medicine (DICOM) is a technical standard for the digital storage and transmission of medical images and related information.
+
+This workflow runs as a command-line application prompting for user input.
+
+1. All the necessary resources are created from an AWS CloudFormation template.
+   1. A HealthImaging data store.
+   2. An Amazon Simple Storage Service (Amazon S3) input bucket for a DICOM import job.
+   3. An Amazon S3 output bucket for a DICOM import job.
+   4. An AWS Identity and Access Management (IAM) role with the appropriate permissions for a DICOM import job.
+
+![CloudFormation stack diagram](../../../../../workflows/healthimaging_image_sets/.images/cfn_stack.png)
+
+2. The user chooses a DICOM study to copy from the [National Cancer Institute Imaging Data Commons (IDC) Collections](https://registry.opendata.aws/nci-imaging-data-commons/)' public S3 bucket.
+
+3. The chosen study is copied to the user's input S3 bucket.
+
+![DICOM copy diagram](../../../../../workflows/healthimaging_image_sets/.images/copy_dicom.png)
+
+4. A HealthImaging DICOM import job is run.
+
+![DICOM import diagram](../../../../../workflows/healthimaging_image_sets/.images/dicom_import.png)
+
+5. The workflow retrieves the IDs for the HealthImaging image frames created by the DICOM import job.
+
+![Image frame ID retrieval diagram](../../../../../workflows/healthimaging_image_sets/.images/get_image_frame_ids.png)
+
+6. The HealthImaging image frames are downloaded, decoded to a bitmap format, and verified using a CRC32 checksum.
+
+7. The created resources can then be deleted, if the user chooses.
+
+## ⚠ Important
+
+- Running this code might result in charges to your AWS account.
+- Running the tests might result in charges to your AWS account.
+- We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+- This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
+
+## Scenario
+
+### Prerequisites
+
+For information on prerequisites for running this scenario, see the main [JavaScript V3 README.md](../../../../README.md).
+
+### Run the Scenario
+
+To run the scenario, follow these steps:
+
+1. Clone the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples) to your local environment.
+2. Navigate to the `javascriptv3/example_code/medical-imaging/scenarios/health-image-sets` directory.
+3. Run the scenario by running `node index.js --scenario <deploy | demo | destroy> [-h|--help] [-y|--yes] [-v|--verbose]`
+
+### Deploy
+This step will prompt you for a name for the CloudFormation stack and the datastore. It will then deploy the stack.
+
+### Demo
+This step copies images from the public bucket, imports them into your datastore, and runs a checksum validation to ensure data integrity.
+
+### Destroy
+This step deletes the image sets from the datastore and deletes the CloudFormation stack. It does not delete saved state that is output from the intermediary steps. Those are left behind for reference. You can delete them by running `rm *state.json` in this directory.
+
+## Additional Resources
+
+- [HealthImaging User Guide](https://docs.aws.amazon.com/healthimaging/latest/devguide/what-is.html)
+- [HealthImaging API Reference](https://docs.aws.amazon.com/healthimaging/latest/APIReference/Welcome.html)
+- [AWS SDK for JavaScript Documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html)
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0

javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/index.js

@@ -0,0 +1,29 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  parseScenarioArgs,
+  Scenario,
+} from "@aws-doc-sdk-examples/lib/scenario/index.js";
+
+import { step1 } from "./step-1.js";
+import { step2 } from "./step-2.js";
+import { step3 } from "./step-3.js";
+import { step4 } from "./step-4.js";
+import { step5 } from "./step-5.js";
+import { step6 } from "./step-6.js";
+import { step7 } from "./step-7.js";
+
+const context = {};
+
+const scenarios = {
+  deploy: new Scenario("Deploy Resources", [step1], context),
+  demo: new Scenario("Run Demo", [step2, step3, step4, step5, step6], context),
+  destroy: new Scenario("Clean Up Resources", [step7], context),
+};
+
+// Call function if run directly
+import { fileURLToPath } from "url";
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  parseScenarioArgs(scenarios);
+}

javascriptv3/example_code/medical-imaging/scenarios/health-image-sets/pixel-data-verification/README.md

@@ -0,0 +1,30 @@
+# AWS HealthImaging Pixel Data Verification
+
+This example demonstrates how to use the AWS HealthImaging (AHI) Pixel Data Verification feature to ensure the image you
+decoded matches the original DICOM P10 Image.
+
+## Dependencies
+
+This example is written in JavaScript and uses NodeJS. It depends on the following libraries:
+
+-   [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3)
+-   [CRC32 Algorithm](https://www.npmjs.com/package/crc-32)
+-   [HTJ2K Decoding](https://github.com/chafey/openjphjs)
+
+## Deployment
+
+1. Check out the project.
+2. Change the current directory to this project: `cd pixel-data-verification`
+3. Install dependencies: `npm install`
+
+## How to use
+
+1. Create a datastore as per the AHLI developer guide.
+2. Import the DICOM file `test/fixtures/CT1_UNC` as per the AHLI developer guide.
+3. Retrieve the ImageSetId from the job output manifest file in S3.
+4. Run this tool passing in your datastore (from step 1), ImageSetId (from step 3), and series and SOP instance UIDs listed below.
+
+```
+$ node index.js $DATASTOREID $IMAGESETID 1.3.6.1.4.1.5962.1.3.1.1.20040826185059.5457 1.3.6.1.4.1.5962.1.1.1.1.1.20040826185059.5457
+CRC32 match!
+```