From 6b6727a9b0612ea462a0f5a1da729cccef087df0 Mon Sep 17 00:00:00 2001
From: Yosef Meller <mellerf@netvision.net.il>
Date: Thu, 5 Nov 2015 11:45:45 +0200
Subject: [PATCH] Try to put more physical understanding into the
 trans_cam_point documentation.

---
 liboptv/src/multimed.c | 46 +++++++++++++++++++-----------------------
 1 file changed, 21 insertions(+), 25 deletions(-)

diff --git a/liboptv/src/multimed.c b/liboptv/src/multimed.c
index c1569f70..ed0da014 100644
--- a/liboptv/src/multimed.c
+++ b/liboptv/src/multimed.c
@@ -111,32 +111,28 @@ double multimed_r_nlay (Calibration *cal, mm_np *mm, vec3d pos) {
     }
 }
 
-
-/*  trans_Cam_Point() creates the shifted points for each position X,Y,Z 
-    Using Exterior and Interior parameters and the Glass vector of the variable
-    window position and the two vectors that point to the crossing point
+/*  trans_Cam_Point() projects global-coordinate points of the camera and an
+    image points on the glass surface separating those points.
     
-    Arguments: 
-    Exterior structure 'ex'
-    multimedia paramaters mm
-    Glass parameters gl
-    3D space position pos
-    Returns:
-    Pointer to ex_t Exterior parameters after shift
-    vector of doubles for shifted position pos_t
-    vector of 3 doubles of cross_p 
-    vector of 3 doubles of cross_c, both used for back projection
-*/ 
-void trans_Cam_Point(Exterior ex
-                   , mm_np mm
-                   , Glass gl
-                   , vec3d pos
-                   , Exterior *ex_t
-                   , vec3d pos_t
-                   , double cross_p[3]
-                   , double cross_c[3]){
-
-/* Beat Luethi June 07: I change the stuff to a system perpendicular to the interface */
+    Input arguments:
+    Exterior ex - holding global-coordinates camera position.
+    mm_np mm - holding glass thickness.
+    Glass gl - holding the glass position in global-coordinates as a 
+        glass-normal vector.
+    vec3d pos - the global coordinates of the observed point.
+    
+    Output arguments:
+    Exterior ex_t - only the primary point fields are used, and are set 
+        to the glass/Z axis intersection.
+    double cross_p[3] - the observed point projection coordinates in global
+        coordinates.
+    double cross_c[3] - same for the camera position. Since the camera point
+        is projected on the other side of the glass, it'll have a small 
+        difference in Z value from ``cross_p``.
+*/
+void trans_Cam_Point(Exterior ex, mm_np mm, Glass gl, vec3d pos, 
+    Exterior *ex_t, vec3d pos_t, double cross_p[3], double cross_c[3])
+{
     double dist_cam_glas,dist_point_glas,dist_o_glas; //glas inside at water 
     int row, col;
     vec3d glass_dir, primary_pt, renorm_glass, temp;