Add Seismic3DOffsetTilesTemplate and Seismic3DReceiverGathersTemplate

- Introduced Seismic3DOffsetTilesTemplate for wide-azimuth seismic data organized by offset vector tiles.
- Added Seismic3DReceiverGathersTemplate for fixed receiver positions, supporting receiver-side processing.
- Updated TemplateRegistry to include new templates.
- Added unit tests for both new templates to ensure functionality and correctness.

Author: BrianMichell

src/mdio/builder/template_registry.py

@@ -25,9 +25,9 @@
 from mdio.builder.templates.seismic_2d_streamer_shot import Seismic2DStreamerShotGathersTemplate
 from mdio.builder.templates.seismic_3d_cdp import Seismic3DCdpGathersTemplate
 from mdio.builder.templates.seismic_3d_coca import Seismic3DCocaGathersTemplate
-from mdio.builder.templates.seismic_3d_obn_receiver import Seismic3DObnReceiverGathersTemplate
-from mdio.builder.templates.seismic_3d_ovt import Seismic3DOffsetVectorTileTemplate
+from mdio.builder.templates.seismic_3d_offset_tiles import Seismic3DOffsetTilesTemplate
 from mdio.builder.templates.seismic_3d_poststack import Seismic3DPostStackTemplate
+from mdio.builder.templates.seismic_3d_receiver_gathers import Seismic3DReceiverGathersTemplate
 from mdio.builder.templates.seismic_3d_streamer_field import Seismic3DStreamerFieldRecordsTemplate
 from mdio.builder.templates.seismic_3d_streamer_shot import Seismic3DStreamerShotGathersTemplate
 
@@ -135,13 +135,12 @@ def _register_default_templates(self) -> None:
         self.register(Seismic3DCocaGathersTemplate("time"))
         self.register(Seismic3DCocaGathersTemplate("depth"))
 
-        # OBN/OBC Receiver Gathers
-        self.register(Seismic3DObnReceiverGathersTemplate("time"))
-        self.register(Seismic3DObnReceiverGathersTemplate("depth"))
+        # Receiver Gathers (OBN, OBC, land fixed-spread) - time domain only
+        self.register(Seismic3DReceiverGathersTemplate())
 
-        # Offset Vector Tile (OVT) Gathers
-        self.register(Seismic3DOffsetVectorTileTemplate("time"))
-        self.register(Seismic3DOffsetVectorTileTemplate("depth"))
+        # Offset Tiles
+        self.register(Seismic3DOffsetTilesTemplate("time"))
+        self.register(Seismic3DOffsetTilesTemplate("depth"))
 
         # Field (shot) data
         self.register(Seismic2DStreamerShotGathersTemplate())

…mdio/builder/templates/seismic_3d_ovt.py …der/templates/seismic_3d_offset_tiles.pysrc/mdio/builder/templates/seismic_3d_ovt.py renamed to src/mdio/builder/templates/seismic_3d_offset_tiles.py src/mdio/builder/templates/seismic_3d_ovt.py renamed to src/mdio/builder/templates/seismic_3d_offset_tiles.py

@@ -1,4 +1,4 @@
-"""Seismic3DOffsetVectorTileTemplate MDIO v1 dataset templates."""
+"""Seismic3DOffsetTilesTemplate MDIO v1 dataset templates."""
 
 from typing import Any
 
@@ -9,8 +9,8 @@
 from mdio.builder.templates.types import SeismicDataDomain
 
 
-class Seismic3DOffsetVectorTileTemplate(AbstractDatasetTemplate):
-    """Seismic Offset Vector Tile (OVT) pre-stack 3D Dataset template.
+class Seismic3DOffsetTilesTemplate(AbstractDatasetTemplate):
+    """Seismic Offset Tiles pre-stack 3D Dataset template.
 
     A 5D template for wide-azimuth seismic data organized by offset vector tiles.
     Data is binned by CDP location (inline, crossline) with offset vector
@@ -53,10 +53,10 @@ def __init__(self, data_domain: SeismicDataDomain = "time"):
 
     @property
     def _name(self) -> str:
-        return f"OffsetVectorTileGathers3D{self._data_domain.capitalize()}"
+        return f"OffsetTiles3D{self._data_domain.capitalize()}"
 
     def _load_dataset_attributes(self) -> dict[str, Any]:
-        return {"surveyType": "3D", "gatherType": "offset_vector_tile"}
+        return {"surveyType": "3D", "gatherType": "offset_tiles"}
 
     def _add_coordinates(self) -> None:
         # Add dimension coordinates

…der/templates/seismic_3d_obn_receiver.py …templates/seismic_3d_receiver_gathers.pysrc/mdio/builder/templates/seismic_3d_obn_receiver.py renamed to src/mdio/builder/templates/seismic_3d_receiver_gathers.py src/mdio/builder/templates/seismic_3d_obn_receiver.py renamed to src/mdio/builder/templates/seismic_3d_receiver_gathers.py

@@ -1,58 +1,60 @@
-"""Seismic3DObnReceiverGathersTemplate MDIO v1 dataset templates."""
+"""Seismic3DReceiverGathersTemplate MDIO v1 dataset templates."""
 
 from typing import Any
 
 from mdio.builder.schemas import compressors
 from mdio.builder.schemas.dtype import ScalarType
 from mdio.builder.schemas.v1.variable import CoordinateMetadata
 from mdio.builder.templates.base import AbstractDatasetTemplate
-from mdio.builder.templates.types import SeismicDataDomain
 
 
-class Seismic3DObnReceiverGathersTemplate(AbstractDatasetTemplate):
-    """Seismic OBN/OBC receiver-domain pre-stack 3D Dataset template.
+class Seismic3DReceiverGathersTemplate(AbstractDatasetTemplate):
+    """Seismic receiver gather pre-stack 3D Dataset template.
 
-    A template for Ocean Bottom Node (OBN) or Ocean Bottom Cable (OBC) surveys where
-    receivers are deployed at fixed positions and shots are organized by shot lines.
-    Data is indexed by receiver position, enabling efficient receiver-side processing.
+    A template for surveys with fixed receiver positions (OBN, OBC, land fixed-spread)
+    where data is organized by receiver position for receiver-side processing.
+    Shots are organized by shot lines with a calculated shot index.
+
+    This template is time-domain only as receiver gathers are typically used
+    for early-stage processing before depth conversion.
 
     Dimensions:
         - receiver: Index of the receiver node/station
         - shot_line: Shot line or swath identifier
-        - shot_point: Shot point within the line
-        - time/depth: Sample dimension
+        - shot_index: Sequential index of shots within the line (calculated, 0-N)
+        - time: Sample dimension
 
     This organization is optimal for:
         - Receiver-side wavefield separation (up/down)
         - Receiver-consistent deconvolution
         - Multi-component processing
-
-    Args:
-        data_domain: The domain of the dataset ('time' or 'depth').
+        - Mirror imaging from OBN
     """
 
-    def __init__(self, data_domain: SeismicDataDomain = "time"):
-        super().__init__(data_domain=data_domain)
+    def __init__(self) -> None:
+        super().__init__(data_domain="time")
 
-        self._dim_names = ("receiver", "shot_line", "shot_point", self._data_domain)
+        self._dim_names = ("receiver", "shot_line", "shot_index", "time")
+        self._calculated_dims = ("shot_index",)
         self._physical_coord_names = (
             "receiver_x",
             "receiver_y",
             "source_coord_x",
             "source_coord_y",
         )
-        self._logical_coord_names = ("receiver_depth",)
+        self._logical_coord_names = ("shot_point",)
         self._var_chunk_shape = (1, 1, 512, 4096)
 
     @property
     def _name(self) -> str:
-        return f"ObnReceiverGathers3D{self._data_domain.capitalize()}"
+        return "ReceiverGathers3D"
 
     def _load_dataset_attributes(self) -> dict[str, Any]:
-        return {"surveyType": "3D", "gatherType": "common_receiver", "acquisitionType": "obn"}
+        return {"surveyType": "3D", "gatherType": "receiver_gathers"}
 
     def _add_coordinates(self) -> None:
         # Add dimension coordinates
+        # Note: shot_index is calculated (0-N), so we don't add a coordinate for it
         self._builder.add_coordinate(
             "receiver",
             dimensions=("receiver",),
@@ -65,12 +67,6 @@ def _add_coordinates(self) -> None:
             data_type=ScalarType.UINT32,
             metadata=CoordinateMetadata(units_v1=self.get_unit_by_key("shot_line")),
         )
-        self._builder.add_coordinate(
-            "shot_point",
-            dimensions=("shot_point",),
-            data_type=ScalarType.UINT32,
-            metadata=CoordinateMetadata(units_v1=self.get_unit_by_key("shot_point")),
-        )
         self._builder.add_coordinate(
             self.trace_domain,
             dimensions=(self.trace_domain,),
@@ -96,25 +92,27 @@ def _add_coordinates(self) -> None:
             compressor=compressor,
             metadata=CoordinateMetadata(units_v1=self.get_unit_by_key("receiver_y")),
         )
+
+        # Shot point coordinate (actual shot point numbers, varies by shot_line and shot_index)
         self._builder.add_coordinate(
-            "receiver_depth",
-            dimensions=("receiver",),
-            data_type=ScalarType.FLOAT32,
+            "shot_point",
+            dimensions=("shot_line", "shot_index"),
+            data_type=ScalarType.UINT32,
             compressor=compressor,
-            metadata=CoordinateMetadata(units_v1=self.get_unit_by_key("receiver_depth")),
+            metadata=CoordinateMetadata(units_v1=self.get_unit_by_key("shot_point")),
         )
 
-        # Source coordinates (vary by shot_line and shot_point)
+        # Source coordinates (vary by shot_line and shot_index)
         self._builder.add_coordinate(
             "source_coord_x",
-            dimensions=("shot_line", "shot_point"),
+            dimensions=("shot_line", "shot_index"),
             data_type=ScalarType.FLOAT64,
             compressor=compressor,
             metadata=CoordinateMetadata(units_v1=self.get_unit_by_key("source_coord_x")),
         )
         self._builder.add_coordinate(
             "source_coord_y",
-            dimensions=("shot_line", "shot_point"),
+            dimensions=("shot_line", "shot_index"),
             data_type=ScalarType.FLOAT64,
             compressor=compressor,
             metadata=CoordinateMetadata(units_v1=self.get_unit_by_key("source_coord_y")),

tests/unit/v1/templates/test_seismic_3d_offset_tiles.py

@@ -0,0 +1,177 @@
+"""Unit tests for Seismic3DOffsetTilesTemplate."""
+
+import pytest
+from tests.unit.v1.helpers import validate_variable
+
+from mdio.builder.schemas.chunk_grid import RegularChunkGrid
+from mdio.builder.schemas.compressors import Blosc
+from mdio.builder.schemas.compressors import BloscCname
+from mdio.builder.schemas.dtype import ScalarType
+from mdio.builder.schemas.dtype import StructuredType
+from mdio.builder.schemas.v1.dataset import Dataset
+from mdio.builder.schemas.v1.units import LengthUnitEnum
+from mdio.builder.schemas.v1.units import LengthUnitModel
+from mdio.builder.schemas.v1.units import TimeUnitEnum
+from mdio.builder.schemas.v1.units import TimeUnitModel
+from mdio.builder.templates.seismic_3d_offset_tiles import Seismic3DOffsetTilesTemplate
+from mdio.builder.templates.types import SeismicDataDomain
+
+UNITS_METER = LengthUnitModel(length=LengthUnitEnum.METER)
+UNITS_SECOND = TimeUnitModel(time=TimeUnitEnum.SECOND)
+
+
+def _validate_coordinates_headers_trace_mask(dataset: Dataset, headers: StructuredType, domain: str) -> None:
+    """Validate the coordinate, headers, trace_mask variables in the dataset."""
+    # Verify variables
+    # 5 dim coords + 2 non-dim coords + 1 data + 1 trace mask + 1 headers = 10 variables
+    assert len(dataset.variables) == 10
+
+    # Verify trace headers
+    validate_variable(
+        dataset,
+        name="headers",
+        dims=[("inline", 256), ("crossline", 256), ("inline_offset_tile", 12), ("crossline_offset_tile", 12)],
+        coords=["cdp_x", "cdp_y"],
+        dtype=headers,
+    )
+
+    validate_variable(
+        dataset,
+        name="trace_mask",
+        dims=[("inline", 256), ("crossline", 256), ("inline_offset_tile", 12), ("crossline_offset_tile", 12)],
+        coords=["cdp_x", "cdp_y"],
+        dtype=ScalarType.BOOL,
+    )
+
+    # Verify dimension coordinate variables
+    validate_variable(
+        dataset,
+        name="inline",
+        dims=[("inline", 256)],
+        coords=["inline"],
+        dtype=ScalarType.INT32,
+    )
+
+    validate_variable(
+        dataset,
+        name="crossline",
+        dims=[("crossline", 256)],
+        coords=["crossline"],
+        dtype=ScalarType.INT32,
+    )
+
+    validate_variable(
+        dataset,
+        name="inline_offset_tile",
+        dims=[("inline_offset_tile", 12)],
+        coords=["inline_offset_tile"],
+        dtype=ScalarType.INT16,
+    )
+
+    validate_variable(
+        dataset,
+        name="crossline_offset_tile",
+        dims=[("crossline_offset_tile", 12)],
+        coords=["crossline_offset_tile"],
+        dtype=ScalarType.INT16,
+    )
+
+    domain_var = validate_variable(
+        dataset,
+        name=domain,
+        dims=[(domain, 2048)],
+        coords=[domain],
+        dtype=ScalarType.INT32,
+    )
+    assert domain_var.metadata.units_v1 in (UNITS_METER, UNITS_SECOND)
+
+    # Verify non-dimension coordinate variables
+    cdp_x = validate_variable(
+        dataset,
+        name="cdp_x",
+        dims=[("inline", 256), ("crossline", 256)],
+        coords=["cdp_x"],
+        dtype=ScalarType.FLOAT64,
+    )
+    assert cdp_x.metadata.units_v1 == UNITS_METER
+
+    cdp_y = validate_variable(
+        dataset,
+        name="cdp_y",
+        dims=[("inline", 256), ("crossline", 256)],
+        coords=["cdp_y"],
+        dtype=ScalarType.FLOAT64,
+    )
+    assert cdp_y.metadata.units_v1 == UNITS_METER
+
+
+@pytest.mark.parametrize("data_domain", ["depth", "time"])
+class TestSeismic3DOffsetTilesTemplate:
+    """Unit tests for Seismic3DOffsetTilesTemplate."""
+
+    def test_configuration(self, data_domain: SeismicDataDomain) -> None:
+        """Unit tests for Seismic3DOffsetTilesTemplate configuration."""
+        t = Seismic3DOffsetTilesTemplate(data_domain=data_domain)
+
+        # Template attributes
+        assert t._dim_names == ("inline", "crossline", "inline_offset_tile", "crossline_offset_tile", data_domain)
+        assert t._physical_coord_names == ("cdp_x", "cdp_y")
+        assert t._logical_coord_names == ()
+        assert t.full_chunk_shape == (4, 4, 6, 6, 4096)
+
+        # Variables instantiated when build_dataset() is called
+        assert t._builder is None
+        assert t._dim_sizes == ()
+
+        # Verify dataset attributes
+        attrs = t._load_dataset_attributes()
+        assert attrs == {"surveyType": "3D", "gatherType": "offset_tiles"}
+        assert t.default_variable_name == "amplitude"
+
+    def test_build_dataset(self, data_domain: SeismicDataDomain, structured_headers: StructuredType) -> None:
+        """Unit tests for Seismic3DOffsetTilesTemplate build."""
+        t = Seismic3DOffsetTilesTemplate(data_domain=data_domain)
+        t.add_units({"cdp_x": UNITS_METER, "cdp_y": UNITS_METER})
+        t.add_units({"time": UNITS_SECOND, "depth": UNITS_METER})
+
+        dataset = t.build_dataset(
+            "Wide Azimuth Offset Tiles",
+            sizes=(256, 256, 12, 12, 2048),
+            header_dtype=structured_headers,
+        )
+
+        assert dataset.metadata.name == "Wide Azimuth Offset Tiles"
+        assert dataset.metadata.attributes["surveyType"] == "3D"
+        assert dataset.metadata.attributes["gatherType"] == "offset_tiles"
+
+        _validate_coordinates_headers_trace_mask(dataset, structured_headers, data_domain)
+
+        # Verify seismic variable
+        seismic = validate_variable(
+            dataset,
+            name="amplitude",
+            dims=[
+                ("inline", 256),
+                ("crossline", 256),
+                ("inline_offset_tile", 12),
+                ("crossline_offset_tile", 12),
+                (data_domain, 2048),
+            ],
+            coords=["cdp_x", "cdp_y"],
+            dtype=ScalarType.FLOAT32,
+        )
+        assert isinstance(seismic.compressor, Blosc)
+        assert seismic.compressor.cname == BloscCname.zstd
+        assert isinstance(seismic.metadata.chunk_grid, RegularChunkGrid)
+        assert seismic.metadata.chunk_grid.configuration.chunk_shape == (4, 4, 6, 6, 4096)
+        assert seismic.metadata.stats_v1 is None
+
+
+@pytest.mark.parametrize("data_domain", ["Time", "DePTh"])
+def test_domain_case_handling(data_domain: str) -> None:
+    """Test that domain parameter handles different cases correctly."""
+    template = Seismic3DOffsetTilesTemplate(data_domain=data_domain)
+    assert template._data_domain == data_domain.lower()
+
+    data_domain_suffix = data_domain.lower().capitalize()
+    assert template.name == f"OffsetTiles3D{data_domain_suffix}"