From 5cfe01d428bb432a51f139412fcf60d1a1dfac08 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Thu, 20 Feb 2025 16:58:14 -0600
Subject: [PATCH] Add `ExternalImage` (#604)

Co-authored-by: Ryan Ly <rly@lbl.gov>
---
 core/nwb.base.yaml                          | 34 +++++++++++++++------
 docs/format/source/format_release_notes.rst |  4 +++
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/core/nwb.base.yaml b/core/nwb.base.yaml
index 859e9045..971a1a36 100644
--- a/core/nwb.base.yaml
+++ b/core/nwb.base.yaml
@@ -23,8 +23,17 @@ datasets:
     VectorData column stores the start_index and count to indicate the range in time
     to be selected as well as an object reference to the TimeSeries.
 
-- neurodata_type_def: Image
+- neurodata_type_def: BaseImage
   neurodata_type_inc: NWBData
+  doc: An abstract base type for image data. Parent type for Image and ExternalImage types.
+  attributes:
+  - name: description
+    dtype: text
+    doc: Description of the image.
+    required: false
+
+- neurodata_type_def: Image
+  neurodata_type_inc: BaseImage
   dtype: numeric
   dims:
   - - x
@@ -44,7 +53,7 @@ datasets:
   - - null
     - null
     - 4
-  doc: An abstract data type for an image. Shape can be 2-D (x, y), or 3-D where the
+  doc: A type for storing image data directly. Shape can be 2-D (x, y), or 3-D where the
     third dimension can have three or four elements, e.g. (x, y, (r, g, b)) or
     (x, y, (r, g, b, a)).
   attributes:
@@ -52,21 +61,26 @@ datasets:
     dtype: float32
     doc: Pixel resolution of the image, in pixels per centimeter.
     required: false
-  - name: description
+
+- neurodata_type_def: ExternalImage
+  neurodata_type_inc: BaseImage
+  doc: A type for referencing an external image file.
+  attributes:
+  - name: file_path
     dtype: text
-    doc: Description of the image.
-    required: false
+    doc: Path or URL to the external image file.
+    required: true
 
 - neurodata_type_def: ImageReferences
   neurodata_type_inc: NWBData
   dtype:
-    target_type: Image
+    target_type: BaseImage
     reftype: object
   dims:
   - num_images
   shape:
   - null
-  doc: Ordered dataset of references to Image objects.
+  doc: Ordered dataset of references to BaseImage (e.g., Image or ExternalImage) objects.
 
 groups:
 - neurodata_type_def: NWBContainer
@@ -253,12 +267,12 @@ groups:
     dtype: text
     doc: Description of this collection of images.
   datasets:
-  - neurodata_type_inc: Image
+  - neurodata_type_inc: BaseImage
     doc: Images stored in this collection.
     quantity: '+'
   - name: order_of_images
     neurodata_type_inc: ImageReferences
-    doc: Ordered dataset of references to Image objects stored in the parent group.
-      Each Image object in the Images group should be stored once and only once, so
+    doc: Ordered dataset of references to BaseImage objects stored in the parent group.
+      Each object in the Images group should be stored once and only once, so
       the dataset should have the same length as the number of images.
     quantity: '?'
diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst
index a8eb3fcc..6ae75875 100644
--- a/docs/format/source/format_release_notes.rst
+++ b/docs/format/source/format_release_notes.rst
@@ -6,6 +6,10 @@ Release Notes
 2.9.0 (Upcoming)
 ----------------
 
+Major changes
+^^^^^^^^^^^^^
+- Added `BaseImage` and `ExternalImage` as new neurodata types. The first so both `Image` and `ExternalImage` can inherit from it. The second to store external images (#604)
+
 Minor changes
 ^^^^^^^^^^^^^
 - Fixed typo and removed HTML tag from doc of behavioral neurodata types. (#600)