feat: add GriddedColorKey decorator for MTEX-style legend rendering

Implements the Decorator pattern: GriddedColorKey wraps any IColorKey
with grid-based flat shading. Colors are precomputed at regular angular
intervals (default 1 degree, matching MTEX) and looked up via nearest-
grid-point snapping. This produces flat-colored patches that hide C1
discontinuities in the underlying color function.

Adds LegendRenderMode enum and setLegendRenderMode() convenience method
to LaueOps for switching between PerPixel (EbsdLib default) and
GridInterpolated (MTEX-style) rendering.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: imikejackson

Source/Apps/generate_ipf_legends.cpp

@@ -18,6 +18,7 @@
 #include "EbsdLib/Utilities/ColorTable.h"
 #include "EbsdLib/Utilities/EbsdStringUtils.hpp"
 #include "EbsdLib/Utilities/FundamentalSectorGeometry.hpp"
+#include "EbsdLib/Utilities/GriddedColorKey.hpp"
 #include "EbsdLib/Utilities/NolzeHielscherColorKey.hpp"
 #include "EbsdLib/Utilities/TSLColorKey.hpp"
 #include "EbsdLib/Utilities/TiffWriter.h"
@@ -374,6 +375,23 @@ void GenerateNolzeHielscherLegends(int imageDim)
     result = TiffWriter::WriteColorImage(ss.str(), imageDim, imageDim, 3, legend->getPointer(0));
     std::cout << ops.getSymmetryName() << " NH Triangle Result: " << result.first << ": " << result.second << std::endl;
 
+    // Set to grid-interpolated mode (MTEX-style rendering)
+    ops.setLegendRenderMode(ebsdlib::LegendRenderMode::GridInterpolated, 1.0);
+
+    // Generate gridded full-circle legend
+    legend = ops.generateIPFTriangleLegend(imageDim, true);
+    ss.str("");
+    ss << k_Output_Dir << "/" << symName << "/" << symName << "_NH_GRIDDED_FULL.tiff";
+    result = TiffWriter::WriteColorImage(ss.str(), imageDim, imageDim, 3, legend->getPointer(0));
+    std::cout << ops.getSymmetryName() << " NH Gridded Full Result: " << result.first << ": " << result.second << std::endl;
+
+    // Generate gridded triangle-only legend
+    legend = ops.generateIPFTriangleLegend(imageDim, false);
+    ss.str("");
+    ss << k_Output_Dir << "/" << symName << "/" << symName << "_NH_GRIDDED.tiff";
+    result = TiffWriter::WriteColorImage(ss.str(), imageDim, imageDim, 3, legend->getPointer(0));
+    std::cout << ops.getSymmetryName() << " NH Gridded Triangle Result: " << result.first << ": " << result.second << std::endl;
+
     // Reset to TSL for subsequent operations
     ops.setColorKey(std::make_shared<ebsdlib::TSLColorKey>());
   }
@@ -393,7 +411,7 @@ int main(int argc, char* argv[])
   }
 
   std::stringstream ss;
-  int imageDim = 512;
+  int imageDim = 1500;
   {
     TrigonalOps ops;
     auto legend = ops.generateIPFTriangleLegend(imageDim, true);

Source/EbsdLib/LaueOps/LaueOps.cpp

@@ -51,6 +51,7 @@
 #include "EbsdLib/Orientation/Quaternion.hpp"
 #include "EbsdLib/Utilities/ColorTable.h"
 #include "EbsdLib/Utilities/ComputeStereographicProjection.h"
+#include "EbsdLib/Utilities/GriddedColorKey.hpp"
 #include "EbsdLib/Utilities/TSLColorKey.hpp"
 
 #include <algorithm> // for std::max
@@ -113,6 +114,32 @@ ebsdlib::IColorKey::Pointer LaueOps::getColorKey() const
   return m_ColorKey;
 }
 
+// -----------------------------------------------------------------------------
+void LaueOps::setLegendRenderMode(ebsdlib::LegendRenderMode mode, double gridResolutionDeg)
+{
+  if(mode == ebsdlib::LegendRenderMode::GridInterpolated)
+  {
+    // Wrap the current color key with a GriddedColorKey if not already wrapped
+    auto currentKey = m_ColorKey;
+    // If already gridded, unwrap first to avoid double-wrapping
+    auto griddedKey = std::dynamic_pointer_cast<ebsdlib::GriddedColorKey>(currentKey);
+    if(griddedKey)
+    {
+      currentKey = griddedKey->innerKey();
+    }
+    m_ColorKey = std::make_shared<ebsdlib::GriddedColorKey>(currentKey, gridResolutionDeg);
+  }
+  else
+  {
+    // PerPixel mode: unwrap if currently gridded
+    auto griddedKey = std::dynamic_pointer_cast<ebsdlib::GriddedColorKey>(m_ColorKey);
+    if(griddedKey)
+    {
+      m_ColorKey = griddedKey->innerKey();
+    }
+  }
+}
+
 // -----------------------------------------------------------------------------
 std::string LaueOps::FZTypeToString(const FZType value)
 {

Source/EbsdLib/LaueOps/LaueOps.h

@@ -46,6 +46,7 @@
 #include "EbsdLib/Orientation/OrientationFwd.hpp"
 #include "EbsdLib/Orientation/Quaternion.hpp"
 #include "EbsdLib/Orientation/Rodrigues.hpp"
+#include "EbsdLib/Utilities/GriddedColorKey.hpp"
 #include "EbsdLib/Utilities/IColorKey.hpp"
 #include "EbsdLib/Utilities/PoleFigureUtilities.h"
 #include "EbsdLib/Utilities/TSLColorKey.hpp"
@@ -302,6 +303,15 @@ class EbsdLib_EXPORT LaueOps
    */
   ebsdlib::IColorKey::Pointer getColorKey() const;
 
+  /**
+   * @brief Set the legend rendering mode.
+   * PerPixel: exact color at every pixel (default, current behavior)
+   * GridInterpolated: MTEX-style flat-shaded grid cells at the given resolution
+   * @param mode The rendering mode to use
+   * @param gridResolutionDeg Grid cell size in degrees (only used for GridInterpolated mode)
+   */
+  void setLegendRenderMode(ebsdlib::LegendRenderMode mode, double gridResolutionDeg = 1.0);
+
   /**
    * @brief generateRodriguesColor Generates an RGB Color from a Rodrigues Vector
    * @param r1 First component of the Rodrigues Vector

Source/EbsdLib/Utilities/GriddedColorKey.cpp

@@ -0,0 +1,106 @@
+#include "EbsdLib/Utilities/GriddedColorKey.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace ebsdlib
+{
+
+namespace
+{
+constexpr double k_Pi = 3.14159265358979323846;
+constexpr double k_HalfPi = k_Pi / 2.0;
+constexpr double k_DegToRad = k_Pi / 180.0;
+} // namespace
+
+GriddedColorKey::GriddedColorKey(IColorKey::Pointer innerKey, double resolutionDeg)
+: m_InnerKey(std::move(innerKey))
+, m_ResolutionDeg(resolutionDeg)
+, m_ResolutionRad(resolutionDeg * k_DegToRad)
+{
+  // Grid covers eta in [0, pi] (180 degrees) and chi in [0, pi/2] (90 degrees)
+  // This covers all possible Laue group SSTs
+  m_EtaSteps = static_cast<int>(std::ceil(180.0 / resolutionDeg)) + 1;
+  m_ChiSteps = static_cast<int>(std::ceil(90.0 / resolutionDeg)) + 1;
+  precomputeGrid();
+}
+
+void GriddedColorKey::precomputeGrid()
+{
+  m_Grid.resize(m_EtaSteps);
+
+  for(int ei = 0; ei < m_EtaSteps; ei++)
+  {
+    m_Grid[ei].resize(m_ChiSteps);
+    double eta = static_cast<double>(ei) * m_ResolutionRad;
+
+    for(int ci = 0; ci < m_ChiSteps; ci++)
+    {
+      double chi = static_cast<double>(ci) * m_ResolutionRad;
+
+      // Convert spherical to Cartesian direction and compute color
+      // via the inner key's Vec3 overload
+      double sinChi = std::sin(chi);
+      double cosChi = std::cos(chi);
+      Vec3 dir = {sinChi * std::cos(eta), sinChi * std::sin(eta), cosChi};
+
+      m_Grid[ei][ci] = m_InnerKey->direction2Color(dir);
+    }
+  }
+}
+
+GriddedColorKey::Vec3 GriddedColorKey::lookupGrid(double eta, double chi) const
+{
+  // Map to grid indices via nearest-neighbor snapping
+  int ei = static_cast<int>(std::round(eta / m_ResolutionRad));
+  int ci = static_cast<int>(std::round(chi / m_ResolutionRad));
+
+  // Clamp to grid bounds
+  ei = std::clamp(ei, 0, m_EtaSteps - 1);
+  ci = std::clamp(ci, 0, m_ChiSteps - 1);
+
+  return m_Grid[ei][ci];
+}
+
+GriddedColorKey::Vec3 GriddedColorKey::direction2Color(const Vec3& direction) const
+{
+  // Convert direction to (eta, chi) and look up from grid
+  double chi = std::acos(std::clamp(direction[2], -1.0, 1.0));
+  double eta = std::atan2(direction[1], direction[0]);
+  if(eta < 0.0)
+  {
+    eta += 2.0 * k_Pi;
+  }
+  return lookupGrid(eta, chi);
+}
+
+GriddedColorKey::Vec3 GriddedColorKey::direction2Color(double eta, double chi, const Vec3& angleLimits) const
+{
+  // Snap eta and chi to nearest grid point (flat shading).
+  // Instead of computing the exact color at (eta, chi),
+  // we return the precomputed color at the nearest grid point.
+  // This produces flat-colored patches like MTEX's surf() rendering.
+  double etaPositive = eta;
+  if(etaPositive < 0.0)
+  {
+    etaPositive += 2.0 * k_Pi;
+  }
+  return lookupGrid(etaPositive, chi);
+}
+
+std::string GriddedColorKey::name() const
+{
+  return m_InnerKey->name() + " (gridded)";
+}
+
+IColorKey::Pointer GriddedColorKey::innerKey() const
+{
+  return m_InnerKey;
+}
+
+double GriddedColorKey::resolutionDeg() const
+{
+  return m_ResolutionDeg;
+}
+
+} // namespace ebsdlib

Source/EbsdLib/Utilities/GriddedColorKey.hpp

@@ -0,0 +1,79 @@
+#pragma once
+
+#include "EbsdLib/EbsdLib.h"
+#include "EbsdLib/Utilities/IColorKey.hpp"
+
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace ebsdlib
+{
+
+/**
+ * @brief Rendering mode for IPF legend generation.
+ */
+enum class LegendRenderMode
+{
+  PerPixel,        ///< Compute exact color at every pixel (EbsdLib default)
+  GridInterpolated ///< Sample at grid points, flat-shade cells (MTEX-style)
+};
+
+/**
+ * @brief Decorator that wraps any IColorKey with grid-based flat shading.
+ *
+ * On construction, precomputes colors at a regular grid of (eta, chi) sample
+ * points by calling the inner color key. When direction2Color() is called,
+ * it snaps the direction to the nearest grid point and returns the precomputed
+ * color (flat shading), producing smooth color patches that hide C1
+ * discontinuities in the underlying color function.
+ *
+ * This replicates the MTEX rendering approach where colors are sampled at
+ * ~1-degree intervals and rendered as flat-colored quadrilateral patches.
+ *
+ * Usage:
+ *   auto nhKey = std::make_shared<NolzeHielscherColorKey>(sector);
+ *   auto gridKey = std::make_shared<GriddedColorKey>(nhKey, 1.0);
+ *   ops.setColorKey(gridKey);
+ */
+class EbsdLib_EXPORT GriddedColorKey : public IColorKey
+{
+public:
+  /**
+   * @brief Construct a grid-decorated color key.
+   * @param innerKey The underlying color key to sample from
+   * @param resolutionDeg Grid cell size in degrees (default 1.0, matching MTEX)
+   */
+  explicit GriddedColorKey(IColorKey::Pointer innerKey, double resolutionDeg = 1.0);
+  ~GriddedColorKey() override = default;
+
+  Vec3 direction2Color(const Vec3& direction) const override;
+  Vec3 direction2Color(double eta, double chi, const Vec3& angleLimits) const override;
+  std::string name() const override;
+
+  /**
+   * @brief Get the underlying (unwrapped) color key.
+   */
+  IColorKey::Pointer innerKey() const;
+
+  /**
+   * @brief Get the grid resolution in degrees.
+   */
+  double resolutionDeg() const;
+
+private:
+  IColorKey::Pointer m_InnerKey;
+  double m_ResolutionRad; // grid cell size in radians
+
+  // Precomputed color grid: m_Grid[etaIdx][chiIdx] = RGB color
+  // Covers eta in [0, pi] and chi in [0, pi/2] to handle all Laue groups
+  std::vector<std::vector<Vec3>> m_Grid;
+  int m_EtaSteps;
+  int m_ChiSteps;
+  double m_ResolutionDeg;
+
+  void precomputeGrid();
+  Vec3 lookupGrid(double eta, double chi) const;
+};
+
+} // namespace ebsdlib

Source/EbsdLib/Utilities/SourceList.cmake

@@ -28,6 +28,7 @@ set(EbsdLib_${DIR_NAME}_HDRS
   ${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/${DIR_NAME}/FundamentalSectorGeometry.hpp
   ${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/${DIR_NAME}/TSLColorKey.hpp
   ${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/${DIR_NAME}/NolzeHielscherColorKey.hpp
+  ${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/${DIR_NAME}/GriddedColorKey.hpp
 )
 
 set(EbsdLib_${DIR_NAME}_SRCS
@@ -47,6 +48,7 @@ set(EbsdLib_${DIR_NAME}_SRCS
   ${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/${DIR_NAME}/FundamentalSectorGeometry.cpp
   ${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/${DIR_NAME}/TSLColorKey.cpp
   ${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/${DIR_NAME}/NolzeHielscherColorKey.cpp
+  ${EbsdLibProj_SOURCE_DIR}/Source/EbsdLib/${DIR_NAME}/GriddedColorKey.cpp
 )
 # # QT5_WRAP_CPP( EbsdLib_Generated_MOC_SRCS ${EbsdLib_Utilities_MOC_HDRS} )
 # set_source_files_properties( ${EbsdLib_Generated_MOC_SRCS} PROPERTIES HEADER_FILE_ONLY TRUE)

Source/Test/CMakeLists.txt

@@ -58,6 +58,7 @@ set(EbsdLib_UnitTest_SRCS
     ${EbsdLibProj_SOURCE_DIR}/Source/Test/FundamentalSectorGeometryTest.cpp
     ${EbsdLibProj_SOURCE_DIR}/Source/Test/TSLColorKeyTest.cpp
     ${EbsdLibProj_SOURCE_DIR}/Source/Test/NolzeHielscherColorKeyTest.cpp
+    ${EbsdLibProj_SOURCE_DIR}/Source/Test/GriddedColorKeyTest.cpp
 )