docs(image loader/metadata provider): Clarify concept + how-to documentation.

packages/docs/docs/concepts/cornerstone-core/metadataProvider.md

@@ -7,18 +7,37 @@ 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<string, any>
+```
+
+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
 
 Since it is possible to register more than one metadata provider, upon adding a provider you can define a priority number for it. When there is a time to request metadata, Cornerstone requests the metadata for `imageId` by the priority order of providers (if provider returns `undefined` for the imageId, Cornerstone moves to the next provider).
 
 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

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,14 +41,16 @@ 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';
     oReq.onreadystatechange = function (oEvent) {
       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

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