camera-client 0.1.2__tar.gz → 0.2.1__tar.gz

{camera_client-0.1.2/camera_client.egg-info → camera_client-0.2.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: camera-client
-Version: 0.1.2
-Summary: Python SDK for camera calibration projection data - transform between distorted, corrected, and world coordinates.
+Version: 0.2.1
+Summary: Python SDK for camera calibration and projection transformations - handle lens distortion, coordinate transformations, and 3D ray casting with symbolic expressions.
 Author-email: Alexander Abramov <extremal.ru@gmail.com>
 License: MIT
 Project-URL: Homepage, https://github.com/avabr/camera-client
 Project-URL: Repository, https://github.com/avabr/camera-client
 Project-URL: Issues, https://github.com/avabr/camera-client/issues
-Keywords: camera,calibration,projection,3d,mathematics
+Keywords: camera,calibration,projection,3d,ray-casting,computer-vision,lens-distortion,coordinate-transformation,sympy
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -25,6 +25,7 @@ Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20.0
+Requires-Dist: sympy>=1.10.0
 Dynamic: license-file
 
 # camera-client
@@ -37,6 +38,8 @@ Python SDK for camera calibration and projection transformations. Transform coor
 - **Multiple coordinate systems** - Transform between source (distorted), corrected, and ground (3D world) coordinates
 - **Lens distortion handling** - Correct for camera lens distortion using calibration lookup tables
 - **Ground plane projection** - Project image coordinates to 3D world coordinates and vice versa
+- **Ray casting** - Generate 3D rays from image coordinates for ray tracing and 3D reconstruction
+- **Sympy-based transformations** - Fast compiled symbolic expressions for mathematical transformations
 - **NumPy-based** - Fast array operations with minimal dependencies
 
 ## Installation
@@ -56,12 +59,13 @@ from camera_client import CameraProjection
 # Load camera calibration data from NPZ archive
 camera = CameraProjection.load("camera_calibration.npz")
 
-# Transform single or multiple points (vectorized operations)
+# Transform multiple points (vectorized operations)
+# Note: All methods require (N, 2) or (N, 3) shaped arrays
 source_points = np.array([
     [100, 200],
     [300, 400],
     [500, 600]
-])
+])  # Shape: (3, 2)
 
 # Remove lens distortion
 corrected_points = camera.src_to_ctd(source_points)
@@ -158,6 +162,28 @@ corrected = camera.src_to_ctd(random_points)
 ground = camera.src_to_gnd(random_points, h=0)
 ```
 
+### Ray Casting (3D Reconstruction)
+
+```python
+# Get 3D rays from image points (useful for ray tracing, 3D reconstruction)
+src_points = np.array([[640, 480], [800, 600]])
+
+# Get ray directions from source (distorted) coordinates
+rays = camera.src_to_ray(src_points)
+print(rays.shape)  # (2, 3) - normalized direction vectors
+
+# Or from corrected coordinates
+ctd_points = camera.src_to_ctd(src_points)
+rays = camera.ctd_to_ray(ctd_points)
+
+# Get camera position in world space (ray origin)
+key_point = camera.get_key_point()
+print(key_point.shape)  # (3,) - [x, y, z] camera position
+
+# Ray equation: point_on_ray = key_point + t * ray_direction
+# All rays are normalized to unit length
+```
+
 ### Accessing Camera Properties
 
 ```python
@@ -186,10 +212,12 @@ Load camera calibration from NPZ file.
 Transform from source (distorted) to corrected coordinates.
 
 **Parameters:**
-- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+- `points` (np.ndarray): Shape **(N, 2)** array of [x, y] coordinates
 
 **Returns:**
-- `np.ndarray`: Shape (N, 2) corrected coordinates
+- `np.ndarray`: Shape **(N, 2)** corrected coordinates
+
+**Note:** Input must be 2D array. For single point use `np.array([[x, y]])`
 
 ---
 
@@ -253,21 +281,67 @@ Transform from 3D ground coordinates to corrected coordinates.
 **Returns:**
 - `np.ndarray`: Shape (N, 2) corrected coordinates
 
+---
+
+### `src_to_ray(points)`
+
+Generate 3D ray directions from source (distorted) image coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 3) normalized ray direction vectors
+
+**Note:** All rays originate from the camera key-point (use `get_key_point()`)
+
+---
+
+### `ctd_to_ray(points)`
+
+Generate 3D ray directions from corrected (undistorted) image coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 3) normalized ray direction vectors
+
+---
+
+### `get_key_point()`
+
+Get the camera position (key-point) in world space.
+
+**Returns:**
+- `np.ndarray`: Shape (3,) array with [x, y, z] camera position
+
 ## Calibration File Format
 
 The calibration file is a NumPy `.npz` archive containing:
 
-- `src2ctd`: Lookup table for source to corrected transformation (H x W x 2)
-- `ctd2src`: Lookup table for corrected to source transformation (H x W x 2)
-- `x_gnd`, `y_gnd`, `z_gnd`: Expression strings for corrected to ground transformation
-- `x_im`, `y_im`: Expression strings for ground to corrected transformation
-- `im_width`, `im_height`: Image dimensions
-- `plan_scale`: Scale factor for ground plane
+### Lookup Tables
+- `src2ctd`: Source to corrected coordinate map (H x W x 2)
+- `ctd2src`: Corrected to source coordinate map (H x W x 2)
+- `map_scale_h`: Height scale values (H x W)
+- `map_scale_w`: Width scale values (H x W)
+- `map_scale_vang`: Vertical angle values (H x W)
+
+### Symbolic Expressions (stored as strings, parsed with SymPy)
+- `exp_im2gnd`: Image to ground coordinate transformation
+- `exp_gnd2im`: Ground to image coordinate transformation
+- `exp_key_point`: Camera key-point (position) in world space
+- `exp_im2ray`: Image to ray direction transformation
+
+### Metadata
+- `im_width`, `im_height`: Image dimensions in pixels
+- `plan_scale`: Scale factor for ground plane coordinates (pixels per meter)
 
 ## Requirements
 
 - Python >= 3.7
 - NumPy >= 1.20.0
+- SymPy >= 1.10.0
 
 ## Links
 
@@ -282,3 +356,8 @@ MIT License - see [LICENSE](LICENSE) file for details.
 ## Author
 
 Alexander Abramov ([extremal.ru@gmail.com](mailto:extremal.ru@gmail.com))
+
+## Upload PyPi
+
+    rm dist/* && python -m build && python -m twine upload dist/*
+    

{camera_client-0.1.2 → camera_client-0.2.1}/README.md

@@ -8,6 +8,8 @@ Python SDK for camera calibration and projection transformations. Transform coor
 - **Multiple coordinate systems** - Transform between source (distorted), corrected, and ground (3D world) coordinates
 - **Lens distortion handling** - Correct for camera lens distortion using calibration lookup tables
 - **Ground plane projection** - Project image coordinates to 3D world coordinates and vice versa
+- **Ray casting** - Generate 3D rays from image coordinates for ray tracing and 3D reconstruction
+- **Sympy-based transformations** - Fast compiled symbolic expressions for mathematical transformations
 - **NumPy-based** - Fast array operations with minimal dependencies
 
 ## Installation
@@ -27,12 +29,13 @@ from camera_client import CameraProjection
 # Load camera calibration data from NPZ archive
 camera = CameraProjection.load("camera_calibration.npz")
 
-# Transform single or multiple points (vectorized operations)
+# Transform multiple points (vectorized operations)
+# Note: All methods require (N, 2) or (N, 3) shaped arrays
 source_points = np.array([
     [100, 200],
     [300, 400],
     [500, 600]
-])
+])  # Shape: (3, 2)
 
 # Remove lens distortion
 corrected_points = camera.src_to_ctd(source_points)
@@ -129,6 +132,28 @@ corrected = camera.src_to_ctd(random_points)
 ground = camera.src_to_gnd(random_points, h=0)
 ```
 
+### Ray Casting (3D Reconstruction)
+
+```python
+# Get 3D rays from image points (useful for ray tracing, 3D reconstruction)
+src_points = np.array([[640, 480], [800, 600]])
+
+# Get ray directions from source (distorted) coordinates
+rays = camera.src_to_ray(src_points)
+print(rays.shape)  # (2, 3) - normalized direction vectors
+
+# Or from corrected coordinates
+ctd_points = camera.src_to_ctd(src_points)
+rays = camera.ctd_to_ray(ctd_points)
+
+# Get camera position in world space (ray origin)
+key_point = camera.get_key_point()
+print(key_point.shape)  # (3,) - [x, y, z] camera position
+
+# Ray equation: point_on_ray = key_point + t * ray_direction
+# All rays are normalized to unit length
+```
+
 ### Accessing Camera Properties
 
 ```python
@@ -157,10 +182,12 @@ Load camera calibration from NPZ file.
 Transform from source (distorted) to corrected coordinates.
 
 **Parameters:**
-- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+- `points` (np.ndarray): Shape **(N, 2)** array of [x, y] coordinates
 
 **Returns:**
-- `np.ndarray`: Shape (N, 2) corrected coordinates
+- `np.ndarray`: Shape **(N, 2)** corrected coordinates
+
+**Note:** Input must be 2D array. For single point use `np.array([[x, y]])`
 
 ---
 
@@ -224,21 +251,67 @@ Transform from 3D ground coordinates to corrected coordinates.
 **Returns:**
 - `np.ndarray`: Shape (N, 2) corrected coordinates
 
+---
+
+### `src_to_ray(points)`
+
+Generate 3D ray directions from source (distorted) image coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 3) normalized ray direction vectors
+
+**Note:** All rays originate from the camera key-point (use `get_key_point()`)
+
+---
+
+### `ctd_to_ray(points)`
+
+Generate 3D ray directions from corrected (undistorted) image coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 3) normalized ray direction vectors
+
+---
+
+### `get_key_point()`
+
+Get the camera position (key-point) in world space.
+
+**Returns:**
+- `np.ndarray`: Shape (3,) array with [x, y, z] camera position
+
 ## Calibration File Format
 
 The calibration file is a NumPy `.npz` archive containing:
 
-- `src2ctd`: Lookup table for source to corrected transformation (H x W x 2)
-- `ctd2src`: Lookup table for corrected to source transformation (H x W x 2)
-- `x_gnd`, `y_gnd`, `z_gnd`: Expression strings for corrected to ground transformation
-- `x_im`, `y_im`: Expression strings for ground to corrected transformation
-- `im_width`, `im_height`: Image dimensions
-- `plan_scale`: Scale factor for ground plane
+### Lookup Tables
+- `src2ctd`: Source to corrected coordinate map (H x W x 2)
+- `ctd2src`: Corrected to source coordinate map (H x W x 2)
+- `map_scale_h`: Height scale values (H x W)
+- `map_scale_w`: Width scale values (H x W)
+- `map_scale_vang`: Vertical angle values (H x W)
+
+### Symbolic Expressions (stored as strings, parsed with SymPy)
+- `exp_im2gnd`: Image to ground coordinate transformation
+- `exp_gnd2im`: Ground to image coordinate transformation
+- `exp_key_point`: Camera key-point (position) in world space
+- `exp_im2ray`: Image to ray direction transformation
+
+### Metadata
+- `im_width`, `im_height`: Image dimensions in pixels
+- `plan_scale`: Scale factor for ground plane coordinates (pixels per meter)
 
 ## Requirements
 
 - Python >= 3.7
 - NumPy >= 1.20.0
+- SymPy >= 1.10.0
 
 ## Links
 
@@ -253,3 +326,8 @@ MIT License - see [LICENSE](LICENSE) file for details.
 ## Author
 
 Alexander Abramov ([extremal.ru@gmail.com](mailto:extremal.ru@gmail.com))
+
+## Upload PyPi
+
+    rm dist/* && python -m build && python -m twine upload dist/*
+    

{camera_client-0.1.2 → camera_client-0.2.1}/camera_client/client.py

@@ -1,5 +1,5 @@
 import numpy as np
-from camera_client.utils import compile_safe_expression
+import sympy as sp
 from camera_client.loading import read_npz_file
 
 
@@ -16,20 +16,6 @@ class CameraProjection:
     - gnd: Ground (3D world) coordinates
     """
 
-    # Allowed variable names for different transformation types
-    VARS_CTD_TO_GND = {
-        "x_im",
-        "y_im",
-        "proj_height",
-        "np",
-        "float64",
-        "asarray",
-        "dtype",
-    }
-    VARS_GND_TO_CTD = {"x_gnd", "y_gnd", "z_gnd", "np", "float64", "asarray", "dtype"}
-    VARS_CTD_TO_RAY = {"x_im", "y_im", "np", "float64", "asarray", "dtype"}
-    VARS_KEYPOINT = {"np", "float64", "asarray", "dtype"}
-
     def __init__(self, cam_archive_data):
         """
         Initialize the camera transformer with calibration data.
@@ -55,66 +41,25 @@ class CameraProjection:
         self.im_size = self.src2ctd_points_map.shape[:2]
 
         # Compile transformation expressions for ctd -> gnd
-        self._x_gnd_func = compile_safe_expression(
-            data["x_gnd"],
-            param_names=["x_im", "y_im", "proj_height"],
-            allowed_vars=self.VARS_CTD_TO_GND,
-        )
-        self._y_gnd_func = compile_safe_expression(
-            data["y_gnd"],
-            param_names=["x_im", "y_im", "proj_height"],
-            allowed_vars=self.VARS_CTD_TO_GND,
-        )
-        self._z_gnd_func = compile_safe_expression(
-            data["z_gnd"],
-            param_names=["x_im", "y_im", "proj_height"],
-            allowed_vars=self.VARS_CTD_TO_GND,
+        x_im, y_im, proj_height = sp.symbols("x_im y_im proj_height")
+        self._lambda_im2gnd = sp.lambdify(
+            (x_im, y_im, proj_height), sp.sympify(data["exp_im2gnd"]), "numpy"
         )
 
         # Compile transformation expressions for gnd -> ctd
-        self._x_im_func = compile_safe_expression(
-            data["x_im"],
-            param_names=["x_gnd", "y_gnd", "z_gnd"],
-            allowed_vars=self.VARS_GND_TO_CTD,
-        )
-        self._y_im_func = compile_safe_expression(
-            data["y_im"],
-            param_names=["x_gnd", "y_gnd", "z_gnd"],
-            allowed_vars=self.VARS_GND_TO_CTD,
+        x_gnd, y_gnd, z_gnd = sp.symbols("x_gnd y_gnd z_gnd")
+        self._lambda_gnd2im = sp.lambdify(
+            (x_gnd, y_gnd, z_gnd), sp.sympify(data["exp_gnd2im"]), "numpy"
         )
 
         # Compile keypoint expressions (camera position in world space)
-        self._x_key_func = compile_safe_expression(
-            data["x_key"],
-            param_names=[],
-            allowed_vars=self.VARS_KEYPOINT,
-        )
-        self._y_key_func = compile_safe_expression(
-            data["y_key"],
-            param_names=[],
-            allowed_vars=self.VARS_KEYPOINT,
-        )
-        self._z_key_func = compile_safe_expression(
-            data["z_key"],
-            param_names=[],
-            allowed_vars=self.VARS_KEYPOINT,
+        self._lambda_key_point = sp.lambdify(
+            (), sp.sympify(data["exp_key_point"]), "numpy"
         )
 
         # Compile ray direction expressions for ctd -> ray
-        self._x_ray_func = compile_safe_expression(
-            data["x_ray"],
-            param_names=["x_im", "y_im"],
-            allowed_vars=self.VARS_CTD_TO_RAY,
-        )
-        self._y_ray_func = compile_safe_expression(
-            data["y_ray"],
-            param_names=["x_im", "y_im"],
-            allowed_vars=self.VARS_CTD_TO_RAY,
-        )
-        self._z_ray_func = compile_safe_expression(
-            data["z_ray"],
-            param_names=["x_im", "y_im"],
-            allowed_vars=self.VARS_CTD_TO_RAY,
+        self._lambda_im2ray = sp.lambdify(
+            (x_im, y_im), sp.sympify(data["exp_im2ray"]), "numpy"
         )
 
     def src_to_ctd(self, points):
@@ -219,64 +164,21 @@ class CameraProjection:
             h: Scalar height or (N,) array of heights for each point
 
         Returns:
-            (N, 3) array of ground points [[x1, y1, z1], ...], with [nan, nan, nan] for invalid
+            (N, 3) array of ground points [[x1, y1, z1], ...]
         """
         points = np.asarray(points, dtype=float)
         if points.ndim != 2 or points.shape[1] != 2:
             raise ValueError(f"Expected (N, 2) array, got shape {points.shape}")
 
-        N = len(points)
-        result = np.full((N, 3), np.nan, dtype=float)
-
-        # Handle scalar or array height
-        if np.isscalar(h):
-            h_array = np.full(N, h, dtype=float)
-        else:
-            h_array = np.asarray(h, dtype=float)
-            if h_array.shape != (N,):
-                raise ValueError(
-                    f"Height array must have shape ({N},), got {h_array.shape}"
-                )
+        N = points.shape[0]
+        x_im, y_im = points.T
+        hs = np.asarray(h, dtype=float)
 
-        # Check for NaN input points
-        valid = ~np.isnan(points).any(axis=1)
-
-        if not valid.any():
-            return result
-
-        # Extract valid points
-        valid_points = points[valid]
-        valid_heights = h_array[valid]
+        # Call lambdified function: returns shape (3, 1, N)
+        # Reshape directly to (N, 3)
+        ps_gnd = np.asarray(self._lambda_im2gnd(x_im, y_im, hs)).reshape(3, N).T
 
-        # Vectorized expression evaluation
-        # NumPy operations in expressions will work element-wise on arrays
-        x_im = valid_points[:, 0]
-        y_im = valid_points[:, 1]
-        proj_height = valid_heights
-
-        # Evaluate expressions (they should handle arrays automatically via NumPy)
-        gnd_x = self._x_gnd_func(x_im, y_im, proj_height)
-        gnd_y = self._y_gnd_func(x_im, y_im, proj_height)
-        gnd_z = self._z_gnd_func(x_im, y_im, proj_height)
-
-        # Stack results and assign to valid indices
-        result[valid] = np.column_stack([gnd_x, gnd_y, gnd_z])
-
-        return result
-
-    def src_to_gnd(self, points, h):
-        """
-        Transform from source to ground coordinates.
-
-        Args:
-            points: (N, 2) array of source points
-            h: Scalar height or (N,) array of heights
-
-        Returns:
-            (N, 3) array of ground points
-        """
-        ctd_points = self.src_to_ctd(points)
-        return self.ctd_to_gnd(ctd_points, h)
+        return ps_gnd
 
     def gnd_to_ctd(self, points):
         """
@@ -286,37 +188,34 @@ class CameraProjection:
             points: (N, 3) array of ground points [[x1, y1, z1], [x2, y2, z2], ...]
 
         Returns:
-            (N, 2) array of image points, with [nan, nan] for invalid
+            (N, 2) array of image points [[x1, y1], ...]
         """
         points = np.asarray(points, dtype=float)
         if points.ndim != 2 or points.shape[1] != 3:
             raise ValueError(f"Expected (N, 3) array, got shape {points.shape}")
 
-        N = len(points)
-        result = np.full((N, 2), np.nan, dtype=float)
+        N = points.shape[0]
+        x_gnd, y_gnd, z_gnd = points.T
 
-        # Check for NaN input points
-        valid = ~np.isnan(points).any(axis=1)
-
-        if not valid.any():
-            return result
-
-        # Extract valid points
-        valid_points = points[valid]
+        # Call lambdified function: returns shape (2, 1, N)
+        # Reshape directly to (N, 2)
+        ps_im = np.asarray(self._lambda_gnd2im(x_gnd, y_gnd, z_gnd)).reshape(2, N).T
 
-        # Vectorized expression evaluation
-        x_gnd = valid_points[:, 0]
-        y_gnd = valid_points[:, 1]
-        z_gnd = valid_points[:, 2]
+        return ps_im
 
-        # Evaluate expressions
-        x_im = self._x_im_func(x_gnd, y_gnd, z_gnd)
-        y_im = self._y_im_func(x_gnd, y_gnd, z_gnd)
+    def src_to_gnd(self, points, h):
+        """
+        Transform from source to ground coordinates.
 
-        # Stack results and assign to valid indices
-        result[valid] = np.column_stack([x_im, y_im])
+        Args:
+            points: (N, 2) array of source points
+            h: Scalar height or (N,) array of heights
 
-        return result
+        Returns:
+            (N, 3) array of ground points
+        """
+        ctd_points = self.src_to_ctd(points)
+        return self.ctd_to_gnd(ctd_points, h)
 
     def gnd_to_src(self, points):
         """
@@ -331,6 +230,16 @@ class CameraProjection:
         ctd_points = self.gnd_to_ctd(points)
         return self.ctd_to_src(ctd_points)
 
+    def get_key_point(self):
+        """
+        Get the key-point of the camera in world space.
+
+        Returns:
+            (3,) 3D coordinates of the key-point of the camera in world space
+        """
+        key_point = self._lambda_key_point()
+        return np.array(key_point, dtype=np.float64).flatten()
+
     def ctd_to_ray(self, points):
         """
         Transform from corrected image coordinates to 3D rays in camera space.
@@ -338,9 +247,8 @@ class CameraProjection:
         Args:
             points: (N, 2) array of corrected image points [[x1, y1], [x2, y2], ...]
 
-        Returns two argiments:
-            - (3,) 3D coordinates of the key-point of the camera in world space
-            - (N, 3) array of ray directions in camera space, with [nan, nan, nan] for invalid
+        Returns:
+            (N, 3) array of ray directions in camera space, with [nan, nan, nan] for invalid
         Ray directions are normalized to unit length.
         The ray for a point is defined as the vector from key-point of the camera.
         """
@@ -348,47 +256,19 @@ class CameraProjection:
         if points.ndim != 2 or points.shape[1] != 2:
             raise ValueError(f"Expected (N, 2) array, got shape {points.shape}")
 
-        N = len(points)
-        ray_directions = np.full((N, 3), np.nan, dtype=float)
-
-        # Calculate keypoint (camera position in world space)
-        # These are typically constants, so we call with no arguments
-        keypoint = np.array(
-            [self._x_key_func(), self._y_key_func(), self._z_key_func()], dtype=float
-        )
-
-        # Check for valid points (not NaN)
-        valid = ~np.isnan(points).any(axis=1)
-
-        if not valid.any():
-            return keypoint, ray_directions
-
-        # Extract valid corrected points
-        valid_points = points[valid]
+        N = points.shape[0]
+        x_im, y_im = points.T
 
-        # Vectorized ray direction evaluation
-        x_im = valid_points[:, 0]
-        y_im = valid_points[:, 1]
-
-        # Evaluate ray direction expressions
-        ray_x = self._x_ray_func(x_im, y_im)
-        ray_y = self._y_ray_func(x_im, y_im)
-        ray_z = self._z_ray_func(x_im, y_im)
-
-        # Stack ray components and ensure float64 dtype
-        # (expressions with large integers can create object dtype arrays)
-        rays = np.column_stack([ray_x, ray_y, ray_z]).astype(np.float64)
+        # Call lambdified function: returns shape (3, 1, N)
+        # Reshape directly to (N, 3)
+        rays = np.asarray(self._lambda_im2ray(x_im, y_im)).reshape(3, N).T
 
         # Normalize ray directions to unit length
         ray_lengths = np.linalg.norm(rays, axis=1, keepdims=True)
-        # Avoid division by zero
         ray_lengths = np.where(ray_lengths > 0, ray_lengths, 1.0)
         rays_normalized = rays / ray_lengths
 
-        # Assign normalized rays to valid indices
-        ray_directions[valid] = rays_normalized
-
-        return keypoint, ray_directions
+        return rays_normalized
 
     def src_to_ray(self, points):
         """
@@ -397,9 +277,8 @@ class CameraProjection:
         Args:
             points: (N, 2) array of source points [[x1, y1], [x2, y2], ...]
 
-        Returns two argiments:
-            - (3,) 3D coordinates of the key-point of the camera in world space
-            - (N, 3) array of ray directions in camera space, with [nan, nan, nan] for invalid
+        Returns:
+            (N, 3) array of ray directions in camera space, with [nan, nan, nan] for invalid
         Ray directions are normalized to unit length.
         The ray for a point is defined as the vector from key-point of the camera.
         """

{camera_client-0.1.2 → camera_client-0.2.1}/camera_client/loading.py

@@ -1,4 +1,5 @@
 import numpy as np
+import sympy as sp
 
 
 # Method 1: Read from a saved file
@@ -20,17 +21,10 @@ def read_npz_file(filename):
             - map_scale_h (np.ndarray): Scalar map of height scale values. Shape: (height, width)
             - map_scale_w (np.ndarray): Scalar map of width scale values. Shape: (height, width)
             - map_scale_vang (np.ndarray): Scalar map of vertical angle values. Shape: (height, width)
-            - x_gnd (str): Symbolic expression for gndal X coordinate perspective transformation
-            - y_gnd (str): Symbolic expression for gndal Y coordinate perspective transformation
-            - z_gnd (str): Symbolic expression for gndal Z coordinate perspective transformation
-            - x_im (str): Symbolic expression for image X coordinate transformation
-            - y_im (str): Symbolic expression for image Y coordinate transformation
-            - x_key (str): Symbolic expression for keypoint X coordinate
-            - y_key (str): Symbolic expression for keypoint Y coordinate
-            - z_key (str): Symbolic expression for keypoint Z coordinate
-            - x_ray (str): Symbolic expression for ray X direction
-            - y_ray (str): Symbolic expression for ray Y direction
-            - z_ray (str): Symbolic expression for ray Z direction
+            - exp_im2gnd (sp.Expr): Sympy expression for image to ground coordinate transformation
+            - exp_gnd2im (sp.Expr): Sympy expression for ground to image coordinate transformation
+            - exp_key_point (sp.Expr): Sympy expression for keypoint coordinates
+            - exp_im2ray (sp.Expr): Sympy expression for image to ray direction transformation
     """
     data = np.load(filename)
 
@@ -45,18 +39,12 @@ def read_npz_file(filename):
     map_scale_w = data["map_scale_w"]
     map_scale_vang = data["map_scale_vang"]
 
-    # String values (convert from numpy string to Python string)
-    x_gnd = str(data["x_gnd_exp"])
-    y_gnd = str(data["y_gnd_exp"])
-    z_gnd = str(data["z_gnd_exp"])
-    x_im = str(data["x_im_exp"])
-    y_im = str(data["y_im_exp"])
-    x_key = str(data["x_key_exp"])
-    y_key = str(data["y_key_exp"])
-    z_key = str(data["z_key_exp"])
-    x_ray = str(data["x_ray_exp"])
-    y_ray = str(data["y_ray_exp"])
-    z_ray = str(data["z_ray_exp"])
+    # String values (convert from sympy srepr to sympy expressions)
+
+    exp_im2gnd = sp.sympify(str(data["exp_im2gnd"]))
+    exp_gnd2im = sp.sympify(str(data["exp_gnd2im"]))
+    exp_key_point = sp.sympify(str(data["exp_key_point"]))
+    exp_im2ray = sp.sympify(str(data["exp_im2ray"]))
 
     # Don't forget to close the file
     data.close()
@@ -70,15 +58,8 @@ def read_npz_file(filename):
         "map_scale_h": map_scale_h,
         "map_scale_w": map_scale_w,
         "map_scale_vang": map_scale_vang,
-        "x_gnd": x_gnd,
-        "y_gnd": y_gnd,
-        "z_gnd": z_gnd,
-        "x_im": x_im,
-        "y_im": y_im,
-        "x_key": x_key,
-        "y_key": y_key,
-        "z_key": z_key,
-        "x_ray": x_ray,
-        "y_ray": y_ray,
-        "z_ray": z_ray,
+        "exp_im2gnd": exp_im2gnd,
+        "exp_gnd2im": exp_gnd2im,
+        "exp_key_point": exp_key_point,
+        "exp_im2ray": exp_im2ray,
     }

{camera_client-0.1.2 → camera_client-0.2.1/camera_client.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: camera-client
-Version: 0.1.2
-Summary: Python SDK for camera calibration projection data - transform between distorted, corrected, and world coordinates.
+Version: 0.2.1
+Summary: Python SDK for camera calibration and projection transformations - handle lens distortion, coordinate transformations, and 3D ray casting with symbolic expressions.
 Author-email: Alexander Abramov <extremal.ru@gmail.com>
 License: MIT
 Project-URL: Homepage, https://github.com/avabr/camera-client
 Project-URL: Repository, https://github.com/avabr/camera-client
 Project-URL: Issues, https://github.com/avabr/camera-client/issues
-Keywords: camera,calibration,projection,3d,mathematics
+Keywords: camera,calibration,projection,3d,ray-casting,computer-vision,lens-distortion,coordinate-transformation,sympy
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -25,6 +25,7 @@ Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20.0
+Requires-Dist: sympy>=1.10.0
 Dynamic: license-file
 
 # camera-client
@@ -37,6 +38,8 @@ Python SDK for camera calibration and projection transformations. Transform coor
 - **Multiple coordinate systems** - Transform between source (distorted), corrected, and ground (3D world) coordinates
 - **Lens distortion handling** - Correct for camera lens distortion using calibration lookup tables
 - **Ground plane projection** - Project image coordinates to 3D world coordinates and vice versa
+- **Ray casting** - Generate 3D rays from image coordinates for ray tracing and 3D reconstruction
+- **Sympy-based transformations** - Fast compiled symbolic expressions for mathematical transformations
 - **NumPy-based** - Fast array operations with minimal dependencies
 
 ## Installation
@@ -56,12 +59,13 @@ from camera_client import CameraProjection
 # Load camera calibration data from NPZ archive
 camera = CameraProjection.load("camera_calibration.npz")
 
-# Transform single or multiple points (vectorized operations)
+# Transform multiple points (vectorized operations)
+# Note: All methods require (N, 2) or (N, 3) shaped arrays
 source_points = np.array([
     [100, 200],
     [300, 400],
     [500, 600]
-])
+])  # Shape: (3, 2)
 
 # Remove lens distortion
 corrected_points = camera.src_to_ctd(source_points)
@@ -158,6 +162,28 @@ corrected = camera.src_to_ctd(random_points)
 ground = camera.src_to_gnd(random_points, h=0)
 ```
 
+### Ray Casting (3D Reconstruction)
+
+```python
+# Get 3D rays from image points (useful for ray tracing, 3D reconstruction)
+src_points = np.array([[640, 480], [800, 600]])
+
+# Get ray directions from source (distorted) coordinates
+rays = camera.src_to_ray(src_points)
+print(rays.shape)  # (2, 3) - normalized direction vectors
+
+# Or from corrected coordinates
+ctd_points = camera.src_to_ctd(src_points)
+rays = camera.ctd_to_ray(ctd_points)
+
+# Get camera position in world space (ray origin)
+key_point = camera.get_key_point()
+print(key_point.shape)  # (3,) - [x, y, z] camera position
+
+# Ray equation: point_on_ray = key_point + t * ray_direction
+# All rays are normalized to unit length
+```
+
 ### Accessing Camera Properties
 
 ```python
@@ -186,10 +212,12 @@ Load camera calibration from NPZ file.
 Transform from source (distorted) to corrected coordinates.
 
 **Parameters:**
-- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+- `points` (np.ndarray): Shape **(N, 2)** array of [x, y] coordinates
 
 **Returns:**
-- `np.ndarray`: Shape (N, 2) corrected coordinates
+- `np.ndarray`: Shape **(N, 2)** corrected coordinates
+
+**Note:** Input must be 2D array. For single point use `np.array([[x, y]])`
 
 ---
 
@@ -253,21 +281,67 @@ Transform from 3D ground coordinates to corrected coordinates.
 **Returns:**
 - `np.ndarray`: Shape (N, 2) corrected coordinates
 
+---
+
+### `src_to_ray(points)`
+
+Generate 3D ray directions from source (distorted) image coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 3) normalized ray direction vectors
+
+**Note:** All rays originate from the camera key-point (use `get_key_point()`)
+
+---
+
+### `ctd_to_ray(points)`
+
+Generate 3D ray directions from corrected (undistorted) image coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 3) normalized ray direction vectors
+
+---
+
+### `get_key_point()`
+
+Get the camera position (key-point) in world space.
+
+**Returns:**
+- `np.ndarray`: Shape (3,) array with [x, y, z] camera position
+
 ## Calibration File Format
 
 The calibration file is a NumPy `.npz` archive containing:
 
-- `src2ctd`: Lookup table for source to corrected transformation (H x W x 2)
-- `ctd2src`: Lookup table for corrected to source transformation (H x W x 2)
-- `x_gnd`, `y_gnd`, `z_gnd`: Expression strings for corrected to ground transformation
-- `x_im`, `y_im`: Expression strings for ground to corrected transformation
-- `im_width`, `im_height`: Image dimensions
-- `plan_scale`: Scale factor for ground plane
+### Lookup Tables
+- `src2ctd`: Source to corrected coordinate map (H x W x 2)
+- `ctd2src`: Corrected to source coordinate map (H x W x 2)
+- `map_scale_h`: Height scale values (H x W)
+- `map_scale_w`: Width scale values (H x W)
+- `map_scale_vang`: Vertical angle values (H x W)
+
+### Symbolic Expressions (stored as strings, parsed with SymPy)
+- `exp_im2gnd`: Image to ground coordinate transformation
+- `exp_gnd2im`: Ground to image coordinate transformation
+- `exp_key_point`: Camera key-point (position) in world space
+- `exp_im2ray`: Image to ray direction transformation
+
+### Metadata
+- `im_width`, `im_height`: Image dimensions in pixels
+- `plan_scale`: Scale factor for ground plane coordinates (pixels per meter)
 
 ## Requirements
 
 - Python >= 3.7
 - NumPy >= 1.20.0
+- SymPy >= 1.10.0
 
 ## Links
 
@@ -282,3 +356,8 @@ MIT License - see [LICENSE](LICENSE) file for details.
 ## Author
 
 Alexander Abramov ([extremal.ru@gmail.com](mailto:extremal.ru@gmail.com))
+
+## Upload PyPi
+
+    rm dist/* && python -m build && python -m twine upload dist/*
+    

{camera_client-0.1.2 → camera_client-0.2.1}/camera_client.egg-info/SOURCES.txt

@@ -7,7 +7,6 @@ setup.py
 camera_client/__init__.py
 camera_client/client.py
 camera_client/loading.py
-camera_client/utils.py
 camera_client.egg-info/PKG-INFO
 camera_client.egg-info/SOURCES.txt
 camera_client.egg-info/dependency_links.txt

{camera_client-0.1.2 → camera_client-0.2.1}/camera_client.egg-info/requires.txt

@@ -1 +1,2 @@
 numpy>=1.20.0
+sympy>=1.10.0

{camera_client-0.1.2 → camera_client-0.2.1}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "camera-client"
-version = "0.1.2"
-description = "Python SDK for camera calibration projection data - transform between distorted, corrected, and world coordinates."
+version = "0.2.1"
+description = "Python SDK for camera calibration and projection transformations - handle lens distortion, coordinate transformations, and 3D ray casting with symbolic expressions."
 readme = "README.md"
 requires-python = ">=3.7"
 license = {text = "MIT"}
 authors = [
     {name = "Alexander Abramov", email = "extremal.ru@gmail.com"},
 ]
-keywords = ["camera", "calibration", "projection", "3d", "mathematics"]
+keywords = ["camera", "calibration", "projection", "3d", "ray-casting", "computer-vision", "lens-distortion", "coordinate-transformation", "sympy"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -29,7 +29,8 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Mathematics",
 ]
 dependencies = [
-    "numpy>=1.20.0"
+    "numpy>=1.20.0",
+    "sympy>=1.10.0"
 ]
 
 [project.urls]

{camera_client-0.1.2 → camera_client-0.2.1}/requirements.txt

@@ -1,3 +1,4 @@
 numpy
+sympy
 matplotlib
 python-dotenv

camera_client-0.1.2/camera_client/utils.py

@@ -1,218 +0,0 @@
-import numpy as np
-import ast
-import operator
-
-
-# ============================================================================
-# Expression Validation and Compilation Functions
-# ============================================================================
-
-# Allowed operations for expression validation
-ALLOWED_OPERATORS = {
-    ast.Add: operator.add,
-    ast.Sub: operator.sub,
-    ast.Mult: operator.mul,
-    ast.Div: operator.truediv,
-    ast.Pow: operator.pow,
-    ast.USub: operator.neg,
-    ast.UAdd: operator.pos,
-}
-
-# Allowed functions
-ALLOWED_FUNCTIONS = {
-    "sqrt": np.sqrt,
-    "sin": np.sin,
-    "cos": np.cos,
-    "tan": np.tan,
-    "arcsin": np.arcsin,
-    "arccos": np.arccos,
-    "arctan": np.arctan,
-    "arctan2": np.arctan2,
-    "abs": np.abs,
-    "exp": np.exp,
-    "log": np.log,
-    "log10": np.log10,
-    "pow": np.power,
-}
-
-
-def normalize_expression(expr):
-    """
-    Normalize expression by replacing common math functions with numpy equivalents.
-
-    Args:
-        expr: String expression to normalize
-
-    Returns:
-        Normalized expression string
-    """
-    # Replace math functions with numpy equivalents
-    # For sqrt, we need special handling to avoid object dtype issues with large integers
-    # We replace sqrt(x) with np.sqrt(np.asarray(x, dtype=np.float64))
-    import re
-
-    # Find all sqrt(...) calls and wrap the argument
-    # Match sqrt followed by parentheses, handling nested parentheses
-    def replace_sqrt(match):
-        return f"np.sqrt(np.asarray({match.group(1)}, dtype=np.float64))"
-
-    # Use regex to find sqrt(...) with balanced parentheses
-    # This pattern matches sqrt( followed by content, handling nested parentheses
-    depth = 0
-    result = []
-    i = 0
-    while i < len(expr):
-        if expr[i:i+4] == 'sqrt':
-            # Found sqrt, now find the matching closing parenthesis
-            if i + 4 < len(expr) and expr[i+4] == '(':
-                start = i + 5  # Start of argument
-                depth = 1
-                j = start
-                while j < len(expr) and depth > 0:
-                    if expr[j] == '(':
-                        depth += 1
-                    elif expr[j] == ')':
-                        depth -= 1
-                    j += 1
-                # j now points to one past the closing paren
-                arg = expr[start:j-1]
-                result.append(f"np.sqrt(np.asarray({arg}, dtype=np.float64))")
-                i = j
-            else:
-                result.append(expr[i])
-                i += 1
-        else:
-            result.append(expr[i])
-            i += 1
-
-    expr = ''.join(result)
-
-    expr = expr.replace("sin(", "np.sin(")
-    expr = expr.replace("cos(", "np.cos(")
-    expr = expr.replace("tan(", "np.tan(")
-    # Handle cases where np.np might occur
-    expr = expr.replace("np.np.", "np.")
-    return expr
-
-
-def validate_expression(expr, allowed_vars):
-    """
-    Validate that expression only contains safe operations.
-
-    Args:
-        expr: String expression to validate
-        allowed_vars: Set of allowed variable names
-
-    Raises:
-        ValueError: If expression contains dangerous operations
-    """
-    try:
-        tree = ast.parse(expr, mode="eval")
-    except SyntaxError as e:
-        raise ValueError(f"Invalid expression syntax: {expr}") from e
-
-    # Walk through AST and check all nodes
-    for node in ast.walk(tree):
-        if isinstance(node, ast.Name):
-            # Check variable names
-            if node.id not in allowed_vars and node.id not in ALLOWED_FUNCTIONS:
-                raise ValueError(
-                    f"Disallowed variable '{node.id}' in expression: {expr}"
-                )
-
-        elif isinstance(node, ast.Call):
-            # Check function calls
-            if isinstance(node.func, ast.Attribute):
-                # Handle np.sqrt, np.sin, etc.
-                if isinstance(node.func.value, ast.Name):
-                    if node.func.value.id != "np":
-                        raise ValueError(
-                            f"Disallowed module '{node.func.value.id}' in expression: {expr}"
-                        )
-                    # np.function_name - allow numpy functions
-                else:
-                    raise ValueError(f"Complex attribute access not allowed: {expr}")
-
-            elif isinstance(node.func, ast.Name):
-                if node.func.id not in ALLOWED_FUNCTIONS:
-                    raise ValueError(
-                        f"Disallowed function '{node.func.id}' in expression: {expr}"
-                    )
-            else:
-                raise ValueError(f"Complex function call not allowed: {expr}")
-
-        elif isinstance(node, ast.BinOp):
-            # Check binary operations
-            if type(node.op) not in ALLOWED_OPERATORS:
-                raise ValueError(
-                    f"Disallowed operator '{node.op.__class__.__name__}' in expression: {expr}"
-                )
-
-        elif isinstance(node, ast.UnaryOp):
-            # Check unary operations
-            if type(node.op) not in ALLOWED_OPERATORS:
-                raise ValueError(
-                    f"Disallowed unary operator '{node.op.__class__.__name__}' in expression: {expr}"
-                )
-
-        elif isinstance(node, (ast.Attribute, ast.Import, ast.ImportFrom)):
-            # Block imports and most attribute access
-            if isinstance(node, ast.Attribute):
-                # Only allow np.function
-                if not (isinstance(node.value, ast.Name) and node.value.id == "np"):
-                    raise ValueError(
-                        f"Disallowed attribute access in expression: {expr}"
-                    )
-            else:
-                raise ValueError(f"Import statements not allowed in expression: {expr}")
-
-        elif isinstance(node, (ast.Lambda, ast.FunctionDef, ast.ClassDef)):
-            raise ValueError(
-                f"Function/class definitions not allowed in expression: {expr}"
-            )
-
-        elif isinstance(node, (ast.ListComp, ast.DictComp, ast.GeneratorExp)):
-            raise ValueError(f"Comprehensions not allowed in expression: {expr}")
-
-
-def compile_safe_expression(expr, param_names, allowed_vars=None):
-    """
-    Validate and compile expression into a callable function.
-
-    Args:
-        expr: String expression to compile
-        param_names: List of parameter names expected in expression
-        allowed_vars: Set of allowed variable names (defaults to param_names + 'np')
-
-    Returns:
-        Compiled function that evaluates the expression
-
-    Raises:
-        ValueError: If expression validation fails
-    """
-    # Default allowed vars to param_names plus 'np'
-    if allowed_vars is None:
-        allowed_vars = set(param_names) | {"np"}
-
-    # Normalize the expression
-    normalized_expr = normalize_expression(expr)
-
-    # Validate the expression
-    validate_expression(normalized_expr, allowed_vars)
-
-    # Compile the expression
-    code = compile(normalized_expr, "<string>", "eval")
-
-    # Create restricted namespace with only allowed functions
-    safe_namespace = {
-        "np": np,
-        "__builtins__": {},  # Remove all builtins
-    }
-    safe_namespace.update(ALLOWED_FUNCTIONS)
-
-    def compiled_func(*args):
-        # Create local namespace with parameter values
-        local_vars = dict(zip(param_names, args))
-        return eval(code, safe_namespace, local_vars)
-
-    return compiled_func