Improve documentation of structs in defs and rename SensorPlacement -> SensorModulePlacement

include/aare/RemapAlgorithm.hpp

@@ -23,11 +23,11 @@ void apply_rotation_shift(defs::GroupConfig &,
 
 defs::StrixelGroupToPixelMap strixel_to_pixel_map(
     defs::GroupConfig const &, defs::SensorPixelGeometry const &,
-    defs::SensorPlacement const &, InclusiveROI const &user_roi,
+    defs::SensorModulePlacement const &, InclusiveROI const &user_roi,
     defs::BondShift bond_shift = {0, 0});
 
 std::vector<defs::StrixelGroupToPixelMap>
-strixel_to_pixel_maps(defs::SensorConfig const &, defs::SensorPlacement const &,
+strixel_to_pixel_maps(defs::SensorConfig const &, defs::SensorModulePlacement const &,
                       InclusiveROI const &user_roi,
                       defs::BondShift bond_shift = {0, 0});
 

include/aare/RemapConfig.hpp

@@ -18,13 +18,13 @@ inline constexpr defs::GroupStrixelGeometry StrxP37{.multiplicity = 2,
 /************************************
  * Default sensor placements
  ************************************/
-inline constexpr defs::SensorPlacement Chip1{
+inline constexpr defs::SensorModulePlacement Chip1{
     .placement_on_module{256, 511, 0, 255},
     .rotation = defs::Rotation::Identity};
-inline constexpr defs::SensorPlacement Chip6{
+inline constexpr defs::SensorModulePlacement Chip6{
     .placement_on_module{512, 767, 256, 511},
     .rotation = defs::Rotation::Rotate180};
-inline constexpr defs::SensorPlacement Quad{
+inline constexpr defs::SensorModulePlacement Quad{
     .placement_on_module{256, 767, 0, 511},
     .rotation = defs::Rotation::Identity};
 
@@ -126,7 +126,7 @@ inline constexpr defs::GroupConfig Quad_iLGAD_bottomhalf{
 
 inline constexpr defs::GroupConfig Quad_iLGAD_tophalf{
     .strixel = StrxP25,
-    .routing = {defs::ColumnModOrdering::Reverse},
+    .routing = {defs::ModuloOrdering::Reverse},
     // Adapt placement to be correct!
     .placement_on_sensor = {
         Quad_iLGAD_pix.guardring.x + 2,                              // 11

include/aare/RemapDefs.hpp

@@ -7,13 +7,41 @@
 
 namespace aare::remap::defs {
 
-// Orientation of the sensor with respect to the ASICs / the HDI
-// Normal means lower part of sensor (as in GDS) aligns with lower part of HDI
+/**
+ * Physical orientation of the sensor on the module.
+ *
+ * This transformation describes how the entire sensor-ASIC assembly (pixel grid
+ * and strixel routing together) is mounted with respect to the module
+ * coordinate system.
+ *
+ * Identity:
+ *   Sensor-ASIC assembly is mounted in its nominal orientation (wire bond pad
+ *   aligns with bottom of HDI).
+ *
+ * Rotate180:
+ *   Sensor-ASIC assembly is rotated by 180° before wire bonding.
+ *   This is equivalent to mirroring both x and y coordinates.
+ */
 enum class Rotation : int { Identity = 0, Rotate180 = 1 };
 
-// enum class Transform : int { Identity, MirrorX, MirrorY, Rotate180 };
-
-enum class ColumnModOrdering { Forward, Reverse };
+/**
+ * Ordering of pixel-to-strixel routing within each multiplicity group.
+ *
+ * Forward:
+ *   Pixels are assigned to strixel rows in increasing column order.
+ *
+ * Reverse:
+ *   The ordering within each multiplicity group is reversed.
+ *
+ * Example (multiplicity = 3):
+ *
+ *   Forward : pixel columns [0,1,2] -> strixel rows [0,1,2]
+ *   Reverse : pixel columns [0,1,2] -> strixel rows [2,1,0]
+ *
+ * This affects only the ordering inside each multiplicity group.
+ * It does not mirror or reorder the groups themselves.
+ */
+enum class ModuloOrdering { Forward, Reverse };
 
 struct Guardring {
     int x;
@@ -25,43 +53,81 @@ struct BondShift {
     int y = 0;
 };
 
-// Define the native pixel grid of the sensor (as connected to ASIC)
+/**
+ * Describes the native ASIC pixel grid of a sensor.
+ *
+ * This geometry is shared by all strixel groups on the sensor and defines
+ * the coordinate system in which remapping is performed.
+ */
 struct SensorPixelGeometry {
     int num_pix_x;
     int num_pix_y;
     Guardring guardring;
 };
 
-// Define the strixel grid of the sensor
+/**
+ * Describes the strixel geometry of a single remapping group.
+ *
+ * Pixel rows are multiplied by `multiplicity`, resulting
+ * in an effective strixel pitch of `pitch_um`, and pixel columns are divided by
+ * `multiplicity`.
+ */
 struct GroupStrixelGeometry {
     int multiplicity;
     double pitch_um;
 };
 
+/**
+ * Describes the routing between ASIC pixel columns and strixel rows
+ * within a remapping group.
+ *
+ * The modulo ordering specifies whether the pixels belonging to each
+ * multiplicity group are mapped in forward or reversed order.
+ */
 struct GroupRouting {
-    ColumnModOrdering mod_order = ColumnModOrdering::Forward;
+    ModuloOrdering mod_order = ModuloOrdering::Forward;
 };
 
-// Fully characterize a strixel group (contiguous area that will be remapped)
+/**
+ * Configuration of a single contiguous strixel group on a sensor.
+ *
+ * A group is characterized by
+ *   - its strixel geometry,
+ *   - its routing pattern, and
+ *   - its location within the native sensor pixel grid.
+ */
 struct GroupConfig {
     GroupStrixelGeometry strixel;
     GroupRouting routing;
-    InclusiveROI placement_on_sensor; // location of the group in the sensor
-                                      // coordinate system (or reduced roi)
+
+    /// Group bounds in native sensor pixel coordinates.
+    InclusiveROI placement_on_sensor;
 };
 
-// Combine multiple strixel areas that make up a single sensor
+/**
+ * Complete description of a sensor.
+ *
+ * A sensor consists of a single native pixel geometry together with one or
+ * more remapping groups that partition the sensor into regions with different
+ * strixel geometries and/or routing.
+ */
 struct SensorConfig {
     SensorPixelGeometry pixel;
     std::vector<GroupConfig> group_configs;
 };
 
-// Define location and orientation of a sensor on the module
-struct SensorPlacement {
-    InclusiveROI placement_on_module; // location of the sensor in full-module
-                                      // coordinate system
+/**
+ * Describes the placement of a sensor within the module.
+ *
+ * Specifies where the sensor is located in module coordinates and how it is
+ * physically oriented with respect to the module reference frame.
+ */
+struct SensorModulePlacement {
+    /// Sensor bounds in module coordinates.
+    InclusiveROI placement_on_module;
+
+    /// Physical orientation of the mounted sensor.
     Rotation rotation;
-    // Transform transform;
 };
 
 // Possibly, this may need to be moved to a dedicated "remapping" class

include/aare/RemapGenerate.hpp

@@ -10,7 +10,7 @@ namespace aare::remap::generate {
  ************************************/
 inline defs::StrixelGroupToPixelMap
 jungfrau_ilgad_singlechip_25um_strixel_map(InclusiveROI rx_roi,
-                                           defs::SensorPlacement placement,
+                                           defs::SensorModulePlacement placement,
                                            defs::BondShift bs = {0, 0}) {
     std::cout << " === JUNGFRAU iLGAD SINGLE-CHIP 25um PITCH === \n";
     return algo::strixel_to_pixel_map(config::jungfrau::SingleChipMP_iLGAD_P25,
@@ -20,7 +20,7 @@ jungfrau_ilgad_singlechip_25um_strixel_map(InclusiveROI rx_roi,
 
 inline defs::StrixelGroupToPixelMap
 jungfrau_ilgad_singlechip_15um_strixel_map(InclusiveROI rx_roi,
-                                           defs::SensorPlacement placement,
+                                           defs::SensorModulePlacement placement,
                                            defs::BondShift bs = {0, 0}) {
     std::cout << " === JUNGFRAU iLGAD SINGLE-CHIP 15um PITCH === \n";
     return algo::strixel_to_pixel_map(config::jungfrau::SingleChipMP_iLGAD_P15,
@@ -30,7 +30,7 @@ jungfrau_ilgad_singlechip_15um_strixel_map(InclusiveROI rx_roi,
 
 inline defs::StrixelGroupToPixelMap
 jungfrau_ilgad_singlechip_18um_strixel_map(InclusiveROI rx_roi,
-                                           defs::SensorPlacement placement,
+                                           defs::SensorModulePlacement placement,
                                            defs::BondShift bs = {0, 0}) {
     std::cout << " === JUNGFRAU iLGAD SINGLE-CHIP 18.75um PITCH === \n";
     return algo::strixel_to_pixel_map(config::jungfrau::SingleChipMP_iLGAD_P18,
@@ -43,7 +43,7 @@ inline std::vector<defs::StrixelGroupToPixelMap>
 jungfrau_ilgad_singlechip_multipitch_strixel_maps(InclusiveROI rx_roi,
                                                   int chip_id = 1,
                                                   defs::BondShift bs = {0, 0}) {
-    defs::SensorPlacement placement;
+    defs::SensorModulePlacement placement;
     if (chip_id == 1)
         placement = config::jungfrau::Chip1;
     else if (chip_id == 6)
@@ -65,7 +65,7 @@ jungfrau_ilgad_singlechip_multipitch_strixel_maps(InclusiveROI rx_roi,
 // More generic overload
 inline std::vector<defs::StrixelGroupToPixelMap>
 jungfrau_ilgad_singlechip_multipitch_strixel_maps(
-    InclusiveROI rx_roi, defs::SensorPlacement placement,
+    InclusiveROI rx_roi, defs::SensorModulePlacement placement,
     defs::BondShift bs = {0, 0}) {
     defs::SensorConfig configs{config::jungfrau::SingleChipMP_iLGAD_pix,
                                {config::jungfrau::SingleChipMP_iLGAD_P25,
@@ -80,7 +80,7 @@ jungfrau_ilgad_singlechip_multipitch_strixel_maps(
  ************************************/
 inline defs::StrixelGroupToPixelMap
 jungfrau_tew_singlechip_25um_strixel_map(InclusiveROI rx_roi,
-                                         defs::SensorPlacement placement,
+                                         defs::SensorModulePlacement placement,
                                          defs::BondShift bs = {0, 0}) {
     std::cout << " === JUNGFRAU TEW SINGLE-CHIP 25um PITCH === \n";
     return algo::strixel_to_pixel_map(config::jungfrau::SingleChipMP_TEW_P25,
@@ -90,7 +90,7 @@ jungfrau_tew_singlechip_25um_strixel_map(InclusiveROI rx_roi,
 
 inline defs::StrixelGroupToPixelMap
 jungfrau_tew_singlechip_15um_strixel_map(InclusiveROI rx_roi,
-                                         defs::SensorPlacement placement,
+                                         defs::SensorModulePlacement placement,
                                          defs::BondShift bs = {0, 0}) {
     std::cout << " === JUNGFRAU TEW SINGLE-CHIP 15um PITCH === \n";
     return algo::strixel_to_pixel_map(config::jungfrau::SingleChipMP_TEW_P15,
@@ -100,7 +100,7 @@ jungfrau_tew_singlechip_15um_strixel_map(InclusiveROI rx_roi,
 
 inline defs::StrixelGroupToPixelMap
 jungfrau_tew_singlechip_18um_strixel_map(InclusiveROI rx_roi,
-                                         defs::SensorPlacement placement,
+                                         defs::SensorModulePlacement placement,
                                          defs::BondShift bs = {0, 0}) {
     std::cout << " === JUNGFRAU TEW SINGLE-CHIP 18.75um PITCH === \n";
     return algo::strixel_to_pixel_map(config::jungfrau::SingleChipMP_TEW_P18,
@@ -113,7 +113,7 @@ inline std::vector<defs::StrixelGroupToPixelMap>
 jungfrau_tew_singlechip_multipitch_strixel_maps(InclusiveROI rx_roi,
                                                 int chip_id = 1,
                                                 defs::BondShift bs = {0, 0}) {
-    defs::SensorPlacement placement;
+    defs::SensorModulePlacement placement;
     if (chip_id == 1)
         placement = config::jungfrau::Chip1;
     else if (chip_id == 6)
@@ -135,7 +135,7 @@ jungfrau_tew_singlechip_multipitch_strixel_maps(InclusiveROI rx_roi,
 // More generic overload
 inline std::vector<defs::StrixelGroupToPixelMap>
 jungfrau_tew_singlechip_multipitch_strixel_maps(InclusiveROI rx_roi,
-                                                defs::SensorPlacement placement,
+                                                defs::SensorModulePlacement placement,
                                                 defs::BondShift bs = {0, 0}) {
     defs::SensorConfig configs{config::jungfrau::SingleChipMP_TEW_pix,
                                {config::jungfrau::SingleChipMP_TEW_P25,
@@ -150,7 +150,7 @@ jungfrau_tew_singlechip_multipitch_strixel_maps(InclusiveROI rx_roi,
  ************************************/
 inline defs::StrixelGroupToPixelMap
 jungfrau_ilgad_quadbottom_25um_strixel_map(InclusiveROI rx_roi,
-                                           defs::SensorPlacement placement) {
+                                           defs::SensorModulePlacement placement) {
     return algo::strixel_to_pixel_map(config::jungfrau::Quad_iLGAD_bottomhalf,
                                       config::jungfrau::Quad_iLGAD_pix,
                                       placement, rx_roi);
@@ -158,7 +158,7 @@ jungfrau_ilgad_quadbottom_25um_strixel_map(InclusiveROI rx_roi,
 
 inline defs::StrixelGroupToPixelMap
 jungfrau_ilgad_quadtop_25um_strixel_map(InclusiveROI rx_roi,
-                                        defs::SensorPlacement placement) {
+                                        defs::SensorModulePlacement placement) {
     return algo::strixel_to_pixel_map(config::jungfrau::Quad_iLGAD_tophalf,
                                       config::jungfrau::Quad_iLGAD_pix,
                                       placement, rx_roi);
@@ -166,7 +166,7 @@ jungfrau_ilgad_quadtop_25um_strixel_map(InclusiveROI rx_roi,
 
 inline std::vector<defs::StrixelGroupToPixelMap>
 jungfrau_ilgad_quad_25um_strixel_maps(InclusiveROI rx_roi,
-                                      defs::SensorPlacement placement) {
+                                      defs::SensorModulePlacement placement) {
 
     defs::SensorConfig configs{config::jungfrau::Quad_iLGAD_pix,
                                {config::jungfrau::Quad_iLGAD_bottomhalf,
@@ -177,7 +177,7 @@ jungfrau_ilgad_quad_25um_strixel_maps(InclusiveROI rx_roi,
 
 inline defs::StrixelGroupToPixelMap
 jungfrau_ilgad_quad_25um_strixel_map(InclusiveROI rx_roi,
-                                     defs::SensorPlacement placement,
+                                     defs::SensorModulePlacement placement,
                                      defs::BondShift bs = {0, 0}) {
     std::vector<int> gap_rows{12, 0};
     auto maps = jungfrau_ilgad_quad_25um_strixel_maps(rx_roi, placement);

src/RemapAlgorithm.cpp

@@ -47,7 +47,7 @@ inline InclusiveROI shift_rotate_roi(InclusiveROI roi,
 defs::StrixelGroupToPixelMap
 strixel_to_pixel_map(defs::GroupConfig const &group_config,
                      defs::SensorPixelGeometry const &pixel,
-                     defs::SensorPlacement const &placement,
+                     defs::SensorModulePlacement const &placement,
                      InclusiveROI const &roi_user, defs::BondShift bond_shift) {
 
     int multiplicity = group_config.strixel.multiplicity;
@@ -67,7 +67,7 @@ strixel_to_pixel_map(defs::GroupConfig const &group_config,
     std::vector<int> mods(multiplicity);
     std::iota(mods.begin(), mods.end(), 0);
 
-    if (group_config.routing.mod_order == defs::ColumnModOrdering::Reverse)
+    if (group_config.routing.mod_order == defs::ModuloOrdering::Reverse)
         std::reverse(mods.begin(), mods.end());
 
     // -- 1) Transform user roi (rx_roi) into sensor-local coordinates
@@ -183,7 +183,7 @@ strixel_to_pixel_map(defs::GroupConfig const &group_config,
 
 std::vector<defs::StrixelGroupToPixelMap>
 strixel_to_pixel_maps(defs::SensorConfig const &sensor_config,
-                      defs::SensorPlacement const &placement,
+                      defs::SensorModulePlacement const &placement,
                       InclusiveROI const &roi_user,
                       defs::BondShift bond_shift) {