ENH: Rename DICOMOrientation to AnatomicalOrientation

Also rename to ToOrientationEnum to indicate the name of the positive direction of the anatomical orientation.
InsightSoftwareConsortium · Aug 14, 2024 · 2502620 · 2502620
1 parent 543cf71
commit 2502620
Show file tree

Hide file tree

Showing 15 changed files with 378 additions and 369 deletions.
diff --git a/...Core/Common/include/itkDICOMOrientation.h → ...Common/include/itkAnatomicalOrientation.h b/...Core/Common/include/itkDICOMOrientation.h → ...Common/include/itkAnatomicalOrientation.h
@@ -15,8 +15,8 @@
  *  limitations under the License.
  *
  *=========================================================================*/
-#ifndef itkDICOMOrientation_h
-#define itkDICOMOrientation_h
+#ifndef itkAnatomicalOrientation_h
+#define itkAnatomicalOrientation_h
 
 #include "ITKCommonExport.h"
 #include "itkImageBase.h"
@@ -29,17 +29,18 @@
 namespace itk
 {
 
-/** \class DICOMOrientation
- * \brief A supporting class for DICOMOrientImageFilter.
+/** \class AnatomicalOrientation
+ * \brief A class to represent anatomical orientations and convert between conventions.
  *
- *  Defines enums to for patient orientation in a compatible way with DICOM.
+ *  Defines patient specific anatomical names to the XYZ axes of a 3D image.
  *
+ * \todo update the details of the enum names in the docs
  *  Instances hold the patient orientation enum and allow conversion to and from enums, string and direction cosine
  * matrices. Conversions from a direction cosine matrix is approximated with the orientation of the closes axes.
  *
  * \ingroup ITKCommon
  */
-class ITKCommon_EXPORT DICOMOrientation
+class ITKCommon_EXPORT AnatomicalOrientation
 {
 public:
   static constexpr unsigned int Dimension = 3;
@@ -53,18 +54,20 @@ class ITKCommon_EXPORT DICOMOrientation
   enum class CoordinateEnum : uint8_t
   {
     UNKNOWN = 0,
-    Left = 2, ///< 0b0010
-    RightToLeft = 2,
+#ifdef ITK_AMBIBUOUS_TO_COORDINATE_ENUMS
+    Left = 2,
     Right = 3,
+    Anterior = 4,
+    Posterior = 5,
+    Superior = 8,
+    Inferior = 9,
+#endif
+    RightToLeft = 2, ///< 0b0010
     LeftToRight = 3,
-    Anterior = 4, ///< front - 0b0100
-    PosteriorToAnterior = 4,
-    Posterior = 5, ///< back
-    AnteriorToPosterior = 5,
-    Superior = 8, ///< above - 0b1000
-    InferiorToSuperior = 8,
-    Inferior = 9, ///< bottom
-    SuperiorToInferior = 9,
+    PosteriorToAnterior = 4, ///< front - 0b0100
+    AnteriorToPosterior = 5, ///< back
+    InferiorToSuperior = 8,  ///< above - 0b1000
+    SuperiorToInferior = 9,  ///< bottom
   };
 
 private:
@@ -76,7 +79,7 @@ class ITKCommon_EXPORT DICOMOrientation
   };
 
   template <CoordinateEnum VPrimary, CoordinateEnum VSecondary, CoordinateEnum VTertiary>
-  static constexpr uint32_t m_ToOrientation =
+  static constexpr uint32_t m_OrientationValue =
     (static_cast<uint32_t>(VPrimary) << static_cast<uint8_t>(CoordinateMajornessTermsEnum::PrimaryMinor)) +
     (static_cast<uint32_t>(VSecondary) << static_cast<uint8_t>(CoordinateMajornessTermsEnum::SecondaryMinor)) +
     (static_cast<uint32_t>(VTertiary) << static_cast<uint8_t>(CoordinateMajornessTermsEnum::TertiaryMinor));
@@ -85,10 +88,10 @@ class ITKCommon_EXPORT DICOMOrientation
   GetCoordinateTerm(CoordinateMajornessTermsEnum cmt) const;
 
 public:
-#define ITK_ORIENTATION_ENUM(P, S, T) m_ToOrientation<P, S, T>
+#define ITK_ORIENTATION_ENUM(P, S, T) m_OrientationValue<P, S, T>
 
 
-  enum class OrientationEnum : uint32_t
+  enum class ToOrientationEnum : uint32_t
 
   {
     INVALID = 0,
@@ -250,9 +253,9 @@ class ITKCommon_EXPORT DICOMOrientation
    *
    * If multiple CoordinateEnums are from the same axes then the Orientation value is INVALID.
    */
-  DICOMOrientation(CoordinateEnum primary, CoordinateEnum secondary, CoordinateEnum tertiary);
+  AnatomicalOrientation(CoordinateEnum primary, CoordinateEnum secondary, CoordinateEnum tertiary);
 
-  DICOMOrientation(OrientationEnum orientation)
+  AnatomicalOrientation(ToOrientationEnum orientation)
     : m_Value(orientation)
   {}
 
@@ -262,16 +265,16 @@ class ITKCommon_EXPORT DICOMOrientation
    *
    * @param legacyOrientation
    */
-  DICOMOrientation(LegacyOrientationType legacyOrientation);
+  AnatomicalOrientation(LegacyOrientationType legacyOrientation);
 #endif
 
-  explicit DICOMOrientation(const DirectionType & d)
+  explicit AnatomicalOrientation(const DirectionType & d)
     : m_Value(DirectionCosinesToOrientation(d))
   {}
 
-  explicit DICOMOrientation(std::string str);
+  explicit AnatomicalOrientation(std::string str);
 
-  operator OrientationEnum() const { return m_Value; }
+  operator ToOrientationEnum() const { return m_Value; }
 
   const std::string &
   GetAsString() const;
@@ -282,7 +285,7 @@ class ITKCommon_EXPORT DICOMOrientation
     return OrientationToDirectionCosines(m_Value);
   }
 
-  OrientationEnum
+  ToOrientationEnum
   GetAsOrientation() const
   {
     return m_Value;
@@ -315,45 +318,45 @@ class ITKCommon_EXPORT DICOMOrientation
   }
 
   /** \brief Return the closest orientation for a direction cosine matrix. */
-  static OrientationEnum
+  static ToOrientationEnum
   DirectionCosinesToOrientation(const DirectionType & dir);
 
   /** \brief Return the direction cosine matrix for a orientation. */
-  static DirectionType OrientationToDirectionCosines(OrientationEnum);
+  static DirectionType OrientationToDirectionCosines(ToOrientationEnum);
 
 
   friend ITKCommon_EXPORT std::ostream &
-                          operator<<(std::ostream & out, OrientationEnum value);
+                          operator<<(std::ostream & out, ToOrientationEnum value);
 
 
 private:
   // Private methods to create the maps, these will only be called once.
-  static std::map<OrientationEnum, std::string>
+  static std::map<ToOrientationEnum, std::string>
   CreateCodeToString();
-  static std::map<std::string, OrientationEnum>
+  static std::map<std::string, ToOrientationEnum>
   CreateStringToCode();
 
   /** \brief Return the global instance of the map from orientation enum to strings.
    *
    * The implementation uses a function static local variable so the global is created only if needed, only once.
    */
-  static const std::map<OrientationEnum, std::string> &
+  static const std::map<ToOrientationEnum, std::string> &
   GetCodeToString();
 
   /** \brief Return the global instance of the map from string to orientation enum.
    */
-  static const std::map<std::string, OrientationEnum> &
+  static const std::map<std::string, ToOrientationEnum> &
   GetStringToCode();
 
-  OrientationEnum m_Value;
+  ToOrientationEnum m_Value;
 };
 
 
 ITKCommon_EXPORT std::ostream &
-                 operator<<(std::ostream & out, typename DICOMOrientation::OrientationEnum value);
+                 operator<<(std::ostream & out, typename AnatomicalOrientation::ToOrientationEnum value);
 
 ITKCommon_EXPORT std::ostream &
-                 operator<<(std::ostream & out, const DICOMOrientation & orientation);
+                 operator<<(std::ostream & out, const AnatomicalOrientation & orientation);
 
 
 } // end namespace itk