Frame: refine critical lens regions

README.md

@@ -147,13 +147,15 @@ production refinement threshold.
 Adaptive refinement is disabled by default (`--refine-max-level 0`), so the
 existing coarse-mesh renders remain unchanged.  When enabled, its defaults are
 an absolute direction error of `1e-3` degrees, relative error `0.1`, minimum
-long edge `0.5` pixels, and minimum area `0.25` pixel-squared.  Each value can
-be overridden independently:
+long edge `0.5` pixels, minimum area `0.25` pixel-squared, and a provisional
+minimum discrete-Jacobian magnitude of `1e-3`.  Each value can be overridden
+independently:
 
 ```text
 --refine-max-level N
 --refine-angle-abs-deg D
 --refine-angle-rel R
+--refine-jacobian-min J
 --refine-min-edge-pixels P
 --refine-min-area-pixels2 A
 ```
@@ -171,8 +173,20 @@ prevent selecting a leaf already at or below the requested image-plane
 long-edge and area scales.
 Triangles whose three vertices disagree between capture and escape are split
 independently of the direction-error thresholds, allowing the mesh to follow a
-shadow boundary.  This first implementation deliberately does not evaluate
-orientation or Jacobian criteria.
+shadow boundary.
+
+Independently of the midpoint geometry test, an all-escaped triangle also
+computes the discrete lens Jacobian
+`J = Omega_source / Omega_image`.  Both signed solid angles use
+`2 atan2(dot(a, cross(b,c)), 1 + dot(a,b) + dot(b,c) + dot(c,a))`, with the
+ordered camera directions for `Omega_image` and their traced infinity
+directions for `Omega_source`.  `abs(J) < --refine-jacobian-min` requests a
+split near a critical curve.  The signed-area calculation retains the sign of
+`J`, but sign changes across adjacent triangles are not currently a refinement
+trigger; this makes it possible to evaluate the `abs(J)` criterion separately.
+The `1e-3` default is deliberately provisional and should be tuned with the
+small Schwarzschild refinement diagnostic before being treated as a production
+threshold.
 
 For a short Schwarzschild diagnostic that permits at most one actual split
 generation, for example:
@@ -181,7 +195,8 @@ generation, for example:
 ./build/schwarzschild_sky --catalog assets/sky_grid_5deg.csv \
   --width 48 --height 48 --coarse-cell-pixels 24 --fov-deg 40 \
   --refine-max-level 1 --refine-angle-abs-deg 0.001 \
-  --refine-angle-rel 0.001 --refine-min-edge-pixels 1 \
+  --refine-angle-rel 0.001 --refine-jacobian-min 0.001 \
+  --refine-min-edge-pixels 1 \
   --refine-min-area-pixels2 1 --draw-mesh \
   --output output/imgs/schwarzschild_refinement.png
 ```