CLAUDE: self-documenting comments: TpTask bridge role, differential...

CLAUDE: self-documenting comments: TpTask bridge role, differential rectification, offset composition

Comment-only (no code change; mvn compile clean). Documents, from Andrey's
explanation: TpTask as the Java<->CUDA work-list bridge; the per-sensor xy
offset as the differential-rectification composed shift (factory kernel
offset + misalignment + disparity + relative pose) split integer/fractional;
historic host-side vs current GPU-side geometry fill; updateTasks() D2H;
disp_dist[cam][4] = d(x,y)/d(disp,ndisp) Jacobian consumed by Corr2dLMA and
lazy-eye/ERS.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/main/java/com/elphel/imagej/gpu/GpuQuad.java

@@ -1026,11 +1026,20 @@ public class GpuQuad{ // quad camera description
 
 	/**
 	 * Update tp_tasks from the GPU after derived coordinates are calculated
+	 *
+	 * The D2H half of the TpTask bridge: after calc_rot_deriv() + calculate_tiles_offsets()
+	 * (geometry_correction.cu) fill the GPU-resident task array with per-sensor xy offsets
+	 * and disp_dist Jacobians computed from the relative pose and per-tile disparity, this
+	 * reads the whole array back and rebuilds the Java TpTask objects — used when the host
+	 * needs the GPU-derived geometry (disparity LMA expected offsets, lazy-eye/ERS).
+	 * See TpTask class javadoc for the full bridge description.
+	 * (Comment by Claude on 07/03/2026, from Andrey's explanation.)
+	 *
 	 * @param tile_tasks tile_tasks array of TpTask prepared by the CPU, will be updated with
 	 * GPU-calculated geometry data
 	 * @param use_aux  Use second (aux) camera (not used now)
 	 */
-	
+
 	public void updateTasks(
 			TpTask [] tile_tasks,
 			boolean use_aux    // while is it in class member? - just to be able to free

src/main/java/com/elphel/imagej/gpu/TpTask.java

@@ -27,6 +27,42 @@ import java.util.Arrays;
 
 import com.elphel.imagej.common.ShowDoubleFloatArrays;
 
+/**
+ * Host-side image of the GPU per-tile task descriptor — the bridge between Java and the
+ * CUDA Tile Processor. Mirrors {@code struct tp_task} (tile_processor_gpu/src/geometry_correction.h)
+ * and is marshalled to/from the GPU as a flat float array (see {@link #asFloatArray} and the
+ * float-array constructor below; ints are bit-cast into floats, layout must match get_task_size()).
+ * <p>
+ * A TpTask array IS the GPU work list: Java decides WHICH 16x16 (stride 8) tiles to process and
+ * with WHAT geometry; kernels (convert_direct, correlate2D, textures) consume it on the GPU.
+ * <p>
+ * The central payload is the per-sensor pixel offset {@code xy[num_sensors][2]} implementing
+ * "differential rectification": no image warping — each sensor is corrected only by its
+ * DIFFERENCE from a common ideal average camera (pure radial distortion, average focal length).
+ * That difference is a per-tile space-variant deconvolution split into a center-symmetrical PSF
+ * kernel plus a pure 2D shift. The full real-valued shift is the SUM of: (1) factory-calibration
+ * kernel center offset, (2) sensor misalignment developed after calibration, (3) target
+ * (expected) disparity, (4) camera pose relative to the reference pose being compensated to.
+ * convert_direct splits that sum into the nearest-integer part (16x16 tile selection from the
+ * source image) and a +/-0.5 pix fractional part applied losslessly in the transform domain by
+ * the phase rotators (shiftTileHor/shiftTileVert) — resampling loss occurs only on the final
+ * return to pixel domain.
+ * <p>
+ * Who fills what: historically Java computed xy/disp_dist per tile per sensor on the host
+ * (GeometryCorrection.getPortsCoordinates()) and the GPU just used them. Currently Java provides
+ * only txy + target_disparity (+ task bits, centerXY, scale) and the GPU computes the per-sensor
+ * offsets itself (geometry_correction.cu: calc_rot_deriv() from the relative pose, then
+ * calculate_tiles_offsets() filling xy and disp_dist in the GPU-resident task array);
+ * GpuQuad.updateTasks() is the D2H readback pulling those GPU-computed values back into these
+ * objects. Planned next: per-tile disparity also becomes GPU-resident (slowly-updated map).
+ * <p>
+ * {@code disp_dist[sensor][4]} is the per-sensor 2x2 Jacobian d(pixel x,y)/d(disparity,
+ * non-disparity) from the same geometry chain; consumed by Corr2dLMA.setMatrices()/
+ * getPairsOffsets() (expected correlation-peak offsets in the disparity LMA) and by the
+ * lazy-eye/ERS accumulation (MultisceneLY, e.g. disp_dist[cam][2] = dy/d(disp)).
+ * <p>
+ * (Documentation by Claude on 07/03/2026, from Andrey's explanation.)
+ */
 public class TpTask {
 	public int        task;
 	// task bits 0..7 - texture neighbors (0 - N, 1 - NE, ..., 7 - NW)