camera-client 0.1.0__py3-none-any.whl

camera_client/__init__.py

@@ -0,0 +1,3 @@
+from camera_client.client import CameraProjection
+
+__all__ = ["CameraProjection"]

camera_client/client.py

@@ -0,0 +1,305 @@
+import numpy as np
+from camera_client.utils import compile_safe_expression
+from camera_client.loading import read_npz_file
+
+
+class CameraProjection:
+    """
+    Vectorized camera coordinate transformer for batch processing.
+
+    This class is optimized for processing multiple points at once.
+    All methods expect array inputs with shape (N, 2) or (N, 3).
+
+    Handles transformations between:
+    - src: Source (distorted) image coordinates
+    - ctd: Corrected (undistorted) image coordinates
+    - gnd: Ground (3D world) coordinates
+    """
+
+    # Allowed variable names for different transformation types
+    VARS_CTD_TO_GND = {"x_im", "y_im", "proj_height", "np"}
+    VARS_GND_TO_CTD = {"x_gnd", "y_gnd", "z_gnd", "np"}
+
+    def __init__(self, cam_archive_data):
+        """
+        Initialize the camera transformer with calibration data.
+
+        Args:
+            cam_archive_data: Dictionary containing:
+                - src2ctd: Source to corrected distortion map (H x W x 2)
+                - ctd2src: Corrected to source distortion map (H x W x 2)
+                - x_gnd, y_gnd, z_gnd: String expressions for ctd -> ground
+                - x_im, y_im: String expressions for ground -> ctd
+        """
+        data = cam_archive_data
+
+        self.plan_scale = data["plan_scale"]
+        self.im_width = data["im_width"]
+        self.im_height = data["im_height"]
+        self.im_wh_size = (self.im_width, self.im_height)
+
+        # Store lookup tables
+        self.src2ctd_points_map = data["src2ctd"]
+        self.ctd2src_points_map = data["ctd2src"]
+
+        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,
+        )
+
+        # 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,
+        )
+
+    def src_to_ctd(self, points):
+        """
+        Transform from source (distorted) to corrected coordinates.
+
+        Args:
+            points: (N, 2) array of source points [[x1, y1], [x2, y2], ...]
+
+        Returns:
+            (N, 2) array of corrected points, with [nan, nan] for out-of-bounds
+        """
+        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, 2), np.nan, dtype=float)
+
+        # Check for NaN input points
+        valid_input = ~np.isnan(points).any(axis=1)
+
+        if not valid_input.any():
+            return result
+
+        # Round to integer coordinates
+        p_int = np.round(points[valid_input]).astype(int)
+
+        # Vectorized bounds checking
+        in_bounds = (
+            (p_int[:, 0] >= 0)
+            & (p_int[:, 0] < self.src2ctd_points_map.shape[1])
+            & (p_int[:, 1] >= 0)
+            & (p_int[:, 1] < self.src2ctd_points_map.shape[0])
+        )
+
+        # Create mask for points that are both valid input and in bounds
+        valid_indices = np.where(valid_input)[0]
+        final_valid_indices = valid_indices[in_bounds]
+        valid_p_int = p_int[in_bounds]
+
+        # Vectorized lookup using advanced indexing
+        # Note: lookup map is [y, x] indexed
+        result[final_valid_indices] = self.src2ctd_points_map[
+            valid_p_int[:, 1], valid_p_int[:, 0]
+        ]
+
+        return result
+
+    def ctd_to_src(self, points):
+        """
+        Transform from corrected to source (distorted) coordinates.
+
+        Args:
+            points: (N, 2) array of corrected points [[x1, y1], [x2, y2], ...]
+
+        Returns:
+            (N, 2) array of source points, with [nan, nan] for out-of-bounds
+        """
+        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, 2), np.nan, dtype=float)
+
+        # Check for NaN input points
+        valid_input = ~np.isnan(points).any(axis=1)
+
+        if not valid_input.any():
+            return result
+
+        # Round to integer coordinates
+        p_int = np.round(points[valid_input]).astype(int)
+
+        # Vectorized bounds checking
+        in_bounds = (
+            (p_int[:, 0] >= 0)
+            & (p_int[:, 0] < self.ctd2src_points_map.shape[1])
+            & (p_int[:, 1] >= 0)
+            & (p_int[:, 1] < self.ctd2src_points_map.shape[0])
+        )
+
+        # Create mask for points that are both valid input and in bounds
+        valid_indices = np.where(valid_input)[0]
+        final_valid_indices = valid_indices[in_bounds]
+        valid_p_int = p_int[in_bounds]
+
+        # Vectorized lookup using advanced indexing
+        result[final_valid_indices] = self.ctd2src_points_map[
+            valid_p_int[:, 1], valid_p_int[:, 0]
+        ]
+
+        return result
+
+    def ctd_to_gnd(self, points, h):
+        """
+        Transform from corrected image coordinates to ground (3D world) coordinates.
+
+        Args:
+            points: (N, 2) array of corrected points [[x1, y1], [x2, y2], ...]
+            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
+        """
+        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}"
+                )
+
+        # 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]
+
+        # 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)
+
+    def gnd_to_ctd(self, points):
+        """
+        Transform from ground (3D world) to corrected image coordinates.
+
+        Args:
+            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
+        """
+        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)
+
+        # 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]
+
+        # Vectorized expression evaluation
+        x_gnd = valid_points[:, 0]
+        y_gnd = valid_points[:, 1]
+        z_gnd = valid_points[:, 2]
+
+        # 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)
+
+        # Stack results and assign to valid indices
+        result[valid] = np.column_stack([x_im, y_im])
+
+        return result
+
+    def gnd_to_src(self, points):
+        """
+        Transform from ground to source coordinates.
+
+        Args:
+            points: (N, 3) array of ground points
+
+        Returns:
+            (N, 2) array of source points
+        """
+        ctd_points = self.gnd_to_ctd(points)
+        return self.ctd_to_src(ctd_points)
+
+    @classmethod
+    def load(cls, archive_path):
+        """
+        Load camera transformer from NPZ archive file.
+
+        Args:
+            archive_path: Path to .npz calibration file
+
+        Returns:
+            CameraProjectionVectorized instance
+        """
+
+        # Convert to regular dict for easier access
+        cam_data = read_npz_file(archive_path)
+
+        return cls(cam_data)

camera_client/loading.py

@@ -0,0 +1,84 @@
+import numpy as np
+
+
+# Method 1: Read from a saved file
+def read_npz_file(filename):
+    """Read camera projection data from saved .npz file.
+
+    Args:
+        filename (str): Path to the .npz file containing camera projection data
+
+    Returns:
+        dict: Dictionary containing the following keys:
+            - plan_scale (float): Scale factor for ground plane coordinates (pixels per meter)
+            - im_width (int): Width of the image in pixels
+            - im_height (int): Height of the image in pixels
+            - src2ctd (np.ndarray): Map of coordinates for undistorted (corrected) image.
+                                   Shape: (height, width, 2) where channel 0 is X, channel 1 is Y
+            - ctd2src (np.ndarray): Map of coordinates for distorted (raw) image based on undistorted.
+                                   Shape: (height, width, 2) where channel 0 is X, channel 1 is Y
+            - 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
+    """
+    data = np.load(filename)
+
+    plan_scale = data["plan_scale"]
+    im_width = data["im_width"]
+    im_height = data["im_height"]
+
+    # Access the arrays
+    src2ctd = data["src2ctd"]
+    ctd2src = data["ctd2src"]
+    map_scale_h = data["map_scale_h"]
+    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"])
+
+    # Don't forget to close the file
+    data.close()
+
+    return {
+        "plan_scale": plan_scale,
+        "im_width": im_width,
+        "im_height": im_height,
+        "src2ctd": src2ctd,
+        "ctd2src": ctd2src,
+        "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,
+    }

camera_client/utils.py

@@ -0,0 +1,178 @@
+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
+    """
+    expr = expr.replace("sqrt", "np.sqrt")
+    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

camera_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: camera-client
+Version: 0.1.0
+Summary: Python SDK for camera calibration projection data - transform between distorted, corrected, and world coordinates.
+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
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Dynamic: license-file
+
+# camera-client
+
+Python SDK for camera calibration and projection transformations. Transform coordinates between distorted image space, corrected image space, and real-world 3D coordinates using pre-computed calibration data.
+
+## Features
+
+- **Vectorized operations** - Process multiple points simultaneously for high performance
+- **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
+- **NumPy-based** - Fast array operations with minimal dependencies
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install camera-client
+```
+
+## Quick Start
+
+```python
+import numpy as np
+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)
+source_points = np.array([
+    [100, 200],
+    [300, 400],
+    [500, 600]
+])
+
+# Remove lens distortion
+corrected_points = camera.src_to_ctd(source_points)
+
+# Project to ground plane (height = 0)
+ground_points = camera.src_to_gnd(source_points, h=0)
+print(ground_points)  # Returns (N, 3) array with [x, y, z] coordinates
+```
+
+## Coordinate Systems
+
+This library handles transformations between three coordinate systems:
+
+- **src** (Source): Distorted image coordinates from the camera
+- **ctd** (Corrected): Undistorted image coordinates after lens correction
+- **gnd** (Ground): Real-world 3D coordinates (x, y, z)
+
+```
+     Distorted                Undistorted              World 3D
+┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
+│                 │      │                 │      │                 │
+│   Source (src)  │ <──> │ Corrected (ctd) │ <──> │  Ground (gnd)   │
+│                 │      │                 │      │                 │
+└─────────────────┘      └─────────────────┘      └─────────────────┘
+   Lens distortion        Lens correction         3D projection
+```
+
+## Usage Examples
+
+### Basic Coordinate Transformations
+
+```python
+from camera_client import CameraProjection
+import numpy as np
+
+# Load calibration data
+camera = CameraProjection.load("camera_calibration.npz")
+
+# Source (distorted) to Corrected (undistorted)
+src_points = np.array([[640, 480], [1280, 720]])
+ctd_points = camera.src_to_ctd(src_points)
+
+# Corrected back to Source
+src_points_back = camera.ctd_to_src(ctd_points)
+
+# Check round-trip accuracy
+error = np.linalg.norm(src_points - src_points_back, axis=1)
+print(f"Round-trip error: {error}")
+```
+
+### 3D Ground Projection
+
+```python
+# Project image points to ground plane
+src_points = np.array([[640, 480], [800, 600]])
+
+# Project to ground at height = 0 (ground level)
+ground_points = camera.src_to_gnd(src_points, h=0)
+print(ground_points)  # Shape: (2, 3) with [x, y, z] coordinates
+
+# Project to elevated plane (e.g., 1.5 meters above ground)
+elevated_points = camera.src_to_gnd(src_points, h=1.5)
+
+# Different height for each point
+heights = np.array([0, 1.5])
+mixed_points = camera.src_to_gnd(src_points, h=heights)
+```
+
+### Reverse Projection (3D to Image)
+
+```python
+# Project 3D world coordinates back to image
+world_points = np.array([
+    [10.0, 5.0, 0.0],    # x, y, z in meters
+    [15.0, 8.0, 1.5]
+])
+
+# Get corrected image coordinates
+ctd_points = camera.gnd_to_ctd(world_points)
+
+# Get source (distorted) image coordinates
+src_points = camera.gnd_to_src(world_points)
+```
+
+### Batch Processing
+
+```python
+# Process large batches of points efficiently
+num_points = 10000
+random_points = np.random.rand(num_points, 2) * [1920, 1080]
+
+# Vectorized transformation (fast!)
+corrected = camera.src_to_ctd(random_points)
+ground = camera.src_to_gnd(random_points, h=0)
+```
+
+### Accessing Camera Properties
+
+```python
+# Get camera dimensions
+print(f"Image size: {camera.im_width} x {camera.im_height}")
+print(f"Image WH: {camera.im_wh_size}")
+print(f"Plan scale: {camera.plan_scale}")
+```
+
+## API Reference
+
+### `CameraProjection.load(archive_path)`
+
+Load camera calibration from NPZ file.
+
+**Parameters:**
+- `archive_path` (str): Path to .npz calibration archive
+
+**Returns:**
+- `CameraProjection` instance
+
+---
+
+### `src_to_ctd(points)`
+
+Transform from source (distorted) to corrected coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 2) corrected coordinates
+
+---
+
+### `ctd_to_src(points)`
+
+Transform from corrected to source (distorted) coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 2) source coordinates
+
+---
+
+### `src_to_gnd(points, h)`
+
+Transform from source coordinates to 3D ground coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+- `h` (float or np.ndarray): Height(s) above ground. Scalar or shape (N,) array
+
+**Returns:**
+- `np.ndarray`: Shape (N, 3) ground coordinates [x, y, z]
+
+---
+
+### `gnd_to_src(points)`
+
+Transform from 3D ground coordinates to source coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 3) array of [x, y, z] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 2) source coordinates
+
+---
+
+### `ctd_to_gnd(points, h)`
+
+Transform from corrected coordinates to 3D ground coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 2) array of [x, y] coordinates
+- `h` (float or np.ndarray): Height(s) above ground
+
+**Returns:**
+- `np.ndarray`: Shape (N, 3) ground coordinates
+
+---
+
+### `gnd_to_ctd(points)`
+
+Transform from 3D ground coordinates to corrected coordinates.
+
+**Parameters:**
+- `points` (np.ndarray): Shape (N, 3) array of [x, y, z] coordinates
+
+**Returns:**
+- `np.ndarray`: Shape (N, 2) corrected coordinates
+
+## 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
+
+## Requirements
+
+- Python >= 3.7
+- NumPy >= 1.20.0
+
+## Links
+
+- **Repository**: [https://github.com/avabr/camera-client](https://github.com/avabr/camera-client)
+- **Issues**: [https://github.com/avabr/camera-client/issues](https://github.com/avabr/camera-client/issues)
+- **PyPI**: [https://pypi.org/project/camera-client/](https://pypi.org/project/camera-client/)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Author
+
+Alexander Abramov ([extremal.ru@gmail.com](mailto:extremal.ru@gmail.com))

camera_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+camera_client/__init__.py,sha256=XAIJyYru2yFfyPVH7bnS17g0PhZ3kOh6KpFHtIAedWc,82
+camera_client/client.py,sha256=_K2nBARp9Y9tLR09ST_t_EBJK77Ys7ne1AaYJBYoOBI,9965
+camera_client/loading.py,sha256=j90sW93vlry2C3jC3yVyvx9bWCKD6ztTwRRZ0_KXkqk,3477
+camera_client/utils.py,sha256=QgZBygEKU5XGFFYn9p68rP08x68yXCXtELsz8iTkwAs,5933
+camera_client-0.1.0.dist-info/licenses/LICENSE,sha256=1i4BjaOpClb6tkjlx0xls3RuF1q2AOeAG0uhG0y_RUU,1065
+camera_client-0.1.0.dist-info/METADATA,sha256=cmV7PczFNE3E0uhQV3Zp6FuSqq2tBWepWTonNjVCQiQ,8511
+camera_client-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+camera_client-0.1.0.dist-info/entry_points.txt,sha256=WR81o3UOxpPbLmVZXnncFFC9-GU1jbxNb0LSG3-2waA,60
+camera_client-0.1.0.dist-info/top_level.txt,sha256=a1RgpRkQgXtlz1R9wYa4FF3b1B_r5Q9ic7TdoCuxlx4,14
+camera_client-0.1.0.dist-info/RECORD,,

camera_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

camera_client-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+camera-client = camera_client.script:main

camera_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

camera_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+camera_client