Add API and implementations to provide axis orientation

components/formats-api/src/loci/formats/AnatomicalOrientation.java

@@ -0,0 +1,131 @@
+/*
+ * #%L
+ * Top-level reader and writer APIs
+ * %%
+ * Copyright (C) 2023 Open Microscopy Environment:
+ *   - Board of Regents of the University of Wisconsin-Madison
+ *   - Glencoe Software, Inc.
+ *   - University of Dundee
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+package loci.formats;
+
+/**
+ * Enum of anatomical orientation terms defined in:
+ * https://ngff.openmicroscopy.org/rfc/4/#permissible-values
+ */
+public enum AnatomicalOrientation implements OrientationTerm {
+  LEFT_TO_RIGHT("left-to-right"),
+  RIGHT_TO_LEFT("right-to-left"),
+  ANTERIOR_TO_POSTERIOR("anterior-to-posterior"),
+  POSTERIOR_TO_ANTERIOR("posterior-to-anterior"),
+  INFERIOR_TO_SUPERIOR("inferior-to-superior"),
+  SUPERIOR_TO_INFERIOR("superior-to-inferior"),
+  DORSAL_TO_VENTRAL("dorsal-to-ventral"),
+  VENTRAL_TO_DORSAL("ventral-to-dorsal"),
+  DORSAL_TO_PALMAR("dorsal-to-palmar"),
+  PALMAR_TO_DORSAL("palmar-to-dorsal"),
+  DORSAL_TO_PLANTAR("dorsal-to-plantar"),
+  PLANTAR_TO_DORSAL("plantar-to-dorsal"),
+  ROSTRAL_TO_CAUDAL("rostral-to-caudal"),
+  CAUDAL_TO_ROSTRAL("caudal-to-rostral"),
+  CRANIAL_TO_CAUDAL("cranial-to-caudal"),
+  CAUDAL_TO_CRANIAL("caudal-to-cranial"),
+  PROXIMAL_TO_DISTAL("proximal-to-distal"),
+  DISTAL_TO_PROXIMAL("distal-to-proximal"),
+  SUPERFICIAL_TO_DEEP("superficial-to-deep"),
+  DEEP_TO_SUPERFICIAL("deep-to-superficial"),
+  APICAL_TO_BASAL("apical-to-basal"),
+  BASAL_TO_APICAL("basal-to-apical"),
+  APEX_TO_BASE("apex-to-base"),
+  BASE_TO_APEX("base-to-apex");
+
+  private String definedTerm;
+
+  private AnatomicalOrientation(String term) {
+    definedTerm = term;
+  }
+
+  @Override
+  public String getDefinedTerm() {
+    return definedTerm;
+  }
+
+  @Override
+  public AnatomicalOrientation flip() {
+    switch (this) {
+      case LEFT_TO_RIGHT:
+        return RIGHT_TO_LEFT;
+      case RIGHT_TO_LEFT:
+        return LEFT_TO_RIGHT;
+      case ANTERIOR_TO_POSTERIOR:
+        return POSTERIOR_TO_ANTERIOR;
+      case POSTERIOR_TO_ANTERIOR:
+        return ANTERIOR_TO_POSTERIOR;
+      case INFERIOR_TO_SUPERIOR:
+        return SUPERIOR_TO_INFERIOR;
+      case SUPERIOR_TO_INFERIOR:
+        return INFERIOR_TO_SUPERIOR;
+      case DORSAL_TO_VENTRAL:
+        return VENTRAL_TO_DORSAL;
+      case VENTRAL_TO_DORSAL:
+        return DORSAL_TO_VENTRAL;
+      case DORSAL_TO_PALMAR:
+        return PALMAR_TO_DORSAL;
+      case PALMAR_TO_DORSAL:
+        return DORSAL_TO_PALMAR;
+      case DORSAL_TO_PLANTAR:
+        return PLANTAR_TO_DORSAL;
+      case PLANTAR_TO_DORSAL:
+        return DORSAL_TO_PLANTAR;
+      case ROSTRAL_TO_CAUDAL:
+        return CAUDAL_TO_ROSTRAL;
+      case CAUDAL_TO_ROSTRAL:
+        return ROSTRAL_TO_CAUDAL;
+      case CRANIAL_TO_CAUDAL:
+        return CAUDAL_TO_CRANIAL;
+      case CAUDAL_TO_CRANIAL:
+        return CRANIAL_TO_CAUDAL;
+      case PROXIMAL_TO_DISTAL:
+        return DISTAL_TO_PROXIMAL;
+      case DISTAL_TO_PROXIMAL:
+        return PROXIMAL_TO_DISTAL;
+      case SUPERFICIAL_TO_DEEP:
+        return DEEP_TO_SUPERFICIAL;
+      case DEEP_TO_SUPERFICIAL:
+        return SUPERFICIAL_TO_DEEP;
+      case APICAL_TO_BASAL:
+        return BASAL_TO_APICAL;
+      case BASAL_TO_APICAL:
+        return APICAL_TO_BASAL;
+      case APEX_TO_BASE:
+        return BASE_TO_APEX;
+      case BASE_TO_APEX:
+        return APEX_TO_BASE;
+      default:
+        throw new IllegalArgumentException(getDefinedTerm());
+    }
+  }
+}

components/formats-api/src/loci/formats/IAxisOrientationReader.java

@@ -0,0 +1,47 @@
+/*
+ * #%L
+ * Top-level reader and writer APIs
+ * %%
+ * Copyright (C) 2023 Open Microscopy Environment:
+ *   - Board of Regents of the University of Wisconsin-Madison
+ *   - Glencoe Software, Inc.
+ *   - University of Dundee
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+package loci.formats;
+
+/**
+ * Interface for reading axis orientation metadata.
+ */
+public interface IAxisOrientationReader {
+
+  /**
+   * Get one orientation object per axis (e.g. "X", "Y"), for the current series.
+   * Order matches getDimensionOrder(). Array elements may be null.
+   */
+  default Orientation[] getAxisOrientations() {
+    return new Orientation[5];
+  }
+}

components/formats-api/src/loci/formats/Orientation.java

@@ -0,0 +1,69 @@
+/*
+ * #%L
+ * Top-level reader and writer APIs
+ * %%
+ * Copyright (C) 2023 Open Microscopy Environment:
+ *   - Board of Regents of the University of Wisconsin-Madison
+ *   - Glencoe Software, Inc.
+ *   - University of Dundee
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+package loci.formats;
+
+/**
+ * Defines an orientation that can be associated with an axis.
+ */
+public class Orientation {
+
+  private OrientationType type;
+
+  private OrientationTerm value;
+
+  public Orientation(OrientationType type, OrientationTerm term) {
+    this.type = type;
+    this.value = term;
+  }
+
+  public void setOrientationType(OrientationType type) {
+    this.type = type;
+  }
+
+  public OrientationType getOrientationType() {
+    return type;
+  }
+
+  public void setOrientationTerm(OrientationTerm term) {
+    value = term;
+  }
+
+  public OrientationTerm getOrientationTerm() {
+    return value;
+  }
+
+  public Orientation flip() {
+    return new Orientation(type, value.flip());
+  }
+
+}

components/formats-api/src/loci/formats/OrientationTerm.java

@@ -0,0 +1,45 @@
+/*
+ * #%L
+ * Top-level reader and writer APIs
+ * %%
+ * Copyright (C) 2023 Open Microscopy Environment:
+ *   - Board of Regents of the University of Wisconsin-Madison
+ *   - Glencoe Software, Inc.
+ *   - University of Dundee
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+package loci.formats;
+
+/**
+ * Common interface for orientation values.
+ */
+public interface OrientationTerm {
+
+  /** @return the defined vocabulary term for the orientation */
+  String getDefinedTerm();
+
+  /** @return the orientation that matches multiplying this orientation's axis by -1 */
+  OrientationTerm flip();
+}

components/formats-api/src/loci/formats/OrientationType.java

@@ -0,0 +1,65 @@
+/*
+ * #%L
+ * Top-level reader and writer APIs
+ * %%
+ * Copyright (C) 2023 Open Microscopy Environment:
+ *   - Board of Regents of the University of Wisconsin-Madison
+ *   - Glencoe Software, Inc.
+ *   - University of Dundee
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+package loci.formats;
+
+/**
+ * Enum of recognized axis orientation types.
+ */
+public enum OrientationType {
+  ANATOMICAL("anatomical", AnatomicalOrientation.class);
+
+  private String definedType;
+  private Class<? extends OrientationTerm> terms;
+
+  private OrientationType(String type, Class<? extends OrientationTerm> terms) {
+    definedType = type;
+    this.terms = terms;
+  }
+
+  public String getDefinedType() {
+    return definedType;
+  }
+
+  public Class<? extends OrientationTerm> getOrientationTermClass() {
+    return terms;
+  }
+
+  public static OrientationType fromString(String type) {
+    for (OrientationType t : OrientationType.class.getEnumConstants()) {
+      if (t.getDefinedType().equals(type)) {
+        return t;
+      }
+    }
+    return null;
+  }
+}

components/formats-bsd/src/loci/formats/dicom/DicomAttribute.java

@@ -225,6 +225,7 @@ public enum DicomAttribute {
     PREGNANCY_STATUS(0x001021c0),
     LAST_MENSTRUAL_DATE(0x001021d0),
     PATIENT_RELIGIOUS_PREFERENCE(0x001021f0),
+    ANATOMICAL_ORIENTATION_TYPE(0x00102210),
     PATIENT_COMMENTS(0x00104000),
     CLINICAL_TRIAL_SPONSOR_NAME(0x00120010),
     CLINICAL_TRIAL_PROTOCOL_ID(0x00120020),