diff --git a/packages/docs/docs/concepts/cornerstone-core/metadataProvider.md b/packages/docs/docs/concepts/cornerstone-core/metadataProvider.md index bd4efe44cf..2b9f9c73ca 100644 --- a/packages/docs/docs/concepts/cornerstone-core/metadataProvider.md +++ b/packages/docs/docs/concepts/cornerstone-core/metadataProvider.md @@ -7,9 +7,33 @@ title: Metadata Providers Medical images typically come with lots of non-pixel-wise metadata such as the pixel spacing of the image, the patient ID, or the scan acquisition date. With some file types (e.g. DICOM), this information is stored within the file header and can be read and parsed and passed around your application. With others (e.g. JPEG, PNG), this information needs to be provided independently from the actual pixel data. Even for DICOM images, however, it is common for application developers to provide metadata independently from the transmission of pixel data from the server to the client since this can considerably improve performance. -A Metadata Provider is a JavaScript function that acts as an interface for accessing metadata related to Images in Cornerstone. Users can define their own provider functions in order to return any metadata they wish for each specific image. +A Metadata Provider is a JavaScript function that acts as an interface for accessing metadata related to Images in Cornerstone. Users can define their own provider functions in order to return any metadata they wish for each specific image. A Metadata Provider function has the following prototype: -Cornerstone provides infrastructure for the definition and usage of metadata providers. Metadata providers are simply functions which take in an [ImageId](./imageId.md) and a specified metadata type, and return the metadata itself. +``` +function metadataProvider(type: string, ...queries: any): any +``` + +However, typically, providers implement the following, more simple prototype: + +``` +function metadataProvider(type: string, imageId: string): Record +``` + +This is because most metadata is provided for [ImageIds](./imageId.md), but Cornerstone provides infrastructure +for the definition and usage of metadata providers for any information. + +## Types of Metadata + +The `type` parameter to a metadata provider can be any string. You can call `cornerstone.metaData.get()` with any type, +and if any metadata provider can provide that type for the given image ID, you get the response. You can use this, for +example, to easily provide application-specific information such as ground truth or patient information. + +Cornerstone core and tools also automatically request various types of metadata for displayed images. A list of standard +metadata modules can be found in the [MetadataModules section](/api/core/namespace/Enums#MetadataModules) of the API reference. +Many of these modules conform to the DICOM standard. If you want to implement them in a [custom metadata +provider](../../how-to-guides/custom-metadata-provider.md), it is easiest to look at how an existing metadata provider +implements them, such as the [WADOURI metadata +provider](https://github.com/cornerstonejs/cornerstone3D/blob/main/packages/dicomImageLoader/src/imageLoader/wadouri/metaData/metaDataProvider.ts#L65). ## Priority of Metadata Providers @@ -17,8 +41,3 @@ Since it is possible to register more than one metadata provider, upon adding a For instance, if provider1 is registered with 10 priority and provider2 is registered with 100 priority, provider2 is asked first for the metadata for the imageId. - -## Skeleton of Metadata Providers - -- A provider should implement a function with `type` and `imageId` arguments -- Additional argument can be added as necessary after imageId diff --git a/packages/docs/docs/how-to-guides/custom-imageLoader.md b/packages/docs/docs/how-to-guides/custom-imageLoader.md index 8fd2df6d78..68b596da39 100644 --- a/packages/docs/docs/how-to-guides/custom-imageLoader.md +++ b/packages/docs/docs/how-to-guides/custom-imageLoader.md @@ -4,7 +4,12 @@ id: custom-image-loader # Custom Image Loader -In this how-to guide we will show you how to create a custom image loader. +In this how-to guide we will show you how to create a custom image loader. You should be familiar with +the following core concepts: + +- [Image Loaders](../concepts/cornerstone-core/imageLoader.md) +- [Image Objects](../concepts/cornerstone-core/images.md) +- [Metadata Providers](../concepts/cornerstone-core/metadataProvider.md) ## Introduction @@ -36,7 +41,7 @@ function loadImage(imageId) { // Create a new Promise const promise = new Promise((resolve, reject) => { // Inside the Promise Constructor, make - // the request for the DICOM data + // the request for the image data const oReq = new XMLHttpRequest(); oReq.open('get', url, true); oReq.responseType = 'arraybuffer'; @@ -44,6 +49,8 @@ function loadImage(imageId) { if (oReq.readyState === 4) { if (oReq.status == 200) { // Request succeeded, Create an image object (logic omitted) + // This may require decoding the image into raw pixel data, determining + // rows/cols, pixel spacing, etc. const image = createImageObject(oReq.response); // Return the image object by resolving the Promise @@ -67,7 +74,15 @@ function loadImage(imageId) { } ``` -### Step 2: Registration of Image Loader +### Step 2: Ensure Image metadata is also available + +Our image loader returns an `imageLoadObject` containing pixel data and related +information, but Cornerstone may also need [additional +metadata](../concepts/cornerstone-core/metadataProvider.md) in order to display +the image. See the [custom metadata provider](custom-metadata-provider.md) documentation +for how to do this. + +### Step 3: Registration of Image Loader After you implement your image loader, you need to register it with Cornerstone. First you need to decide which URL scheme your image loader supports. Let's say your image loader diff --git a/packages/docs/docs/how-to-guides/custom-metadata-provider.md b/packages/docs/docs/how-to-guides/custom-metadata-provider.md index fbd4eb1f11..1b670740d6 100644 --- a/packages/docs/docs/how-to-guides/custom-metadata-provider.md +++ b/packages/docs/docs/how-to-guides/custom-metadata-provider.md @@ -4,7 +4,12 @@ id: custom-metadata-provider # Custom Metadata Provider -In this how-to guide we will show you how to create a custom metadata provider. +In this how-to guide we will show you how to create a custom metadata provider. You should be familiar with +the following core concepts: + +- [Image Loaders](../concepts/cornerstone-core/imageLoader.md) +- [Image Objects](../concepts/cornerstone-core/images.md) +- [Metadata Providers](../concepts/cornerstone-core/metadataProvider.md) ## Introduction