lab-camera-optimizer 1.0.0__tar.gz → 1.0.2__tar.gz

lab_camera_optimizer-1.0.2/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+recursive-include configs *.yaml
+

{lab_camera_optimizer-1.0.0 → lab_camera_optimizer-1.0.2}/PKG-INFO

@@ -1,31 +1,9 @@
 Metadata-Version: 2.4
 Name: lab-camera-optimizer
-Version: 1.0.0
+Version: 1.0.2
 Summary: Automated camera placement optimiser for markerless biomechanics motion capture labs
 Author: Florian Delaplace
-License: MIT License
-        
-        Copyright (c) 2026 Florian Delaplace
-        
-        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.
-        
-        
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/flodelaplace/lab-camera-optimizer
 Project-URL: Repository, https://github.com/flodelaplace/lab-camera-optimizer
 Project-URL: Documentation, https://github.com/flodelaplace/lab-camera-optimizer/blob/main/ALGORITHM.md
@@ -35,7 +13,6 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Scientific/Engineering
 Classifier: Intended Audience :: Science/Research
@@ -56,6 +33,8 @@ Given a room layout, a set of cameras and a capture zone, this tool finds the
 configuration that maximises 3D body coverage (head-to-toe visibility) across
 all evaluation points, with optional bilateral coverage constraints.
 
+![Project overview](docs/Lab_camera_optimizer_overview.png)
+
 ---
 
 ## Features
@@ -92,14 +71,23 @@ all evaluation points, with optional bilateral coverage constraints.
 ### Option A — pip install (recommended)
 
 ```bash
-pip install git+https://github.com/flodelaplace/lab-camera-optimizer.git
+pip install lab-camera-optimizer
+```
+
+Then initialise a working directory with the example configs:
+
+```bash
+mkdir my-lab && cd my-lab
+lab-camera-init
 ```
 
-Once installed, two commands are available anywhere in your terminal:
+This copies the example YAML configs into `configs/` and creates the `outputs/`
+folder in your current directory. Three commands are then available:
 
 ```bash
-lab-camera-optimizer --config path/to/my_lab.yaml
-lab-camera-preview   --config path/to/my_lab.yaml
+lab-camera-init                                        # copy example configs (run once)
+lab-camera-preview   --config configs/example_simple.yaml
+lab-camera-optimizer --config configs/example_simple.yaml
 ```
 
 ### Option B — Clone and run locally

{lab_camera_optimizer-1.0.0 → lab_camera_optimizer-1.0.2}/README.md

@@ -6,6 +6,8 @@ Given a room layout, a set of cameras and a capture zone, this tool finds the
 configuration that maximises 3D body coverage (head-to-toe visibility) across
 all evaluation points, with optional bilateral coverage constraints.
 
+![Project overview](docs/Lab_camera_optimizer_overview.png)
+
 ---
 
 ## Features
@@ -42,14 +44,23 @@ all evaluation points, with optional bilateral coverage constraints.
 ### Option A — pip install (recommended)
 
 ```bash
-pip install git+https://github.com/flodelaplace/lab-camera-optimizer.git
+pip install lab-camera-optimizer
+```
+
+Then initialise a working directory with the example configs:
+
+```bash
+mkdir my-lab && cd my-lab
+lab-camera-init
 ```
 
-Once installed, two commands are available anywhere in your terminal:
+This copies the example YAML configs into `configs/` and creates the `outputs/`
+folder in your current directory. Three commands are then available:
 
 ```bash
-lab-camera-optimizer --config path/to/my_lab.yaml
-lab-camera-preview   --config path/to/my_lab.yaml
+lab-camera-init                                        # copy example configs (run once)
+lab-camera-preview   --config configs/example_simple.yaml
+lab-camera-optimizer --config configs/example_simple.yaml
 ```
 
 ### Option B — Clone and run locally

lab_camera_optimizer-1.0.2/configs/T_zone_direction_change.yaml

@@ -0,0 +1,200 @@
+# =============================================================
+# Lab Camera Optimizer — T-shaped capture zone
+# Use case: approach run + 90° direction change at the END
+#
+# Room  : 12m × 7m rectangle with a small structural pillar
+# Cameras: 10 wall-mounted cameras at 2.0m or 2.2m height
+#
+# T-shape (RELATIVE coordinates, junction at the end of the run):
+#
+#                        [8,-1.5]──[10,-1.5]
+#                          │  left   │     ← turn left  priority 1.8
+#                          │  turn   │
+#  [0,0]──────────────────[8, 0]──[10, 0]
+#    │   approach (8m×1m)  │ inter  │      priority 1.0 / 2.5
+#  [0,1]──────────────────[8, 1]──[10, 1]
+#                          │  right  │     ← turn right priority 1.8
+#                          │  turn   │
+#                        [8, 2.5]──[10,2.5]
+#
+#  Approach arm : X=0→8,  Y=0→1   (8m long × 1m wide)
+#  Turn arm     : X=8→10, Y=-1.5→2.5  (2m wide × 4m total)
+#  Intersection : X=8→10, Y=0→1   (2m × 1m — end of run)
+#
+#  The whole T translates via x_offsets / y_offsets.
+# =============================================================
+
+# ─────────────────────────────────────────────────────────────
+# 1. ROOM
+# ─────────────────────────────────────────────────────────────
+room:
+  corners:
+    - [0,  0]
+    - [12, 0]
+    - [12, 7]
+    - [0,  7]
+  height: 3.0
+
+# ─────────────────────────────────────────────────────────────
+# 2. OBSTACLES
+# ─────────────────────────────────────────────────────────────
+obstacles:
+  - type: rect
+    bounds: [5.8, 0.0, 6.1, 0.3]
+    height: 3.0
+    label: "Pillar"
+    can_mount_camera: false
+
+# ─────────────────────────────────────────────────────────────
+# 3. SUBJECT
+# ─────────────────────────────────────────────────────────────
+subject:
+  height: 1.9
+  foot_z: 0.0
+
+# ─────────────────────────────────────────────────────────────
+# 4. CAMERA SETS
+# ─────────────────────────────────────────────────────────────
+camera_sets:
+
+  - id: "cam_A"
+    name: "Wall camera"
+    mounting: "wall"
+    optional: false
+    fov_h_landscape: 110.0
+    fov_v_landscape:  70.0
+    fov_h_portrait:   70.0
+    fov_v_portrait:  110.0
+    max_range: 12.0
+    min_range:  0.5
+    height_options: [2.0, 2.2]
+    max_count:   10
+    min_spacing: 1.2
+    score_weight: 1.0
+    color: "#1f77b4"
+
+  - id: "cam_B"
+    name: "Tripod camera"
+    mounting: "tripod"
+    optional: true
+    fov_h_landscape:  80.0
+    fov_v_landscape:  58.0
+    fov_h_portrait:   58.0
+    fov_v_portrait:   80.0
+    max_range: 8.0
+    min_range: 0.5
+    height_options: [1.5]
+    max_count: 0          # disabled — set > 0 to re-enable
+    min_spacing: 1.5
+    walk_axis_margin: 0.7
+    score_weight: 0.6
+    color: "#d62728"
+
+# ─────────────────────────────────────────────────────────────
+# 5. CAPTURE ZONES
+# ─────────────────────────────────────────────────────────────
+#
+# All coordinates are RELATIVE.
+# The entire T moves together via the shared x_offsets / y_offsets.
+#
+#  Visual (relative coords):
+#
+#                        [8,-1.5]──[10,-1.5]
+#                           │  LEFT   │
+#                           │  TURN   │   priority 1.8
+#  [0,0]──────────────────[8, 0 ]──[10, 0]
+#    │                     ║ INTER ║
+#    │  APPROACH  (8m×1m)  ║  2.5  ║   priority 1.0
+#    │                     ║       ║
+#  [0,1]──────────────────[8, 1 ]──[10, 1]
+#                           │  RIGHT  │
+#                           │  TURN   │   priority 1.8
+#                        [8, 2.5]──[10,2.5]
+#
+capture_zones:
+
+  # ── Level 1 : approach corridor (8m × 1m) ────────────────────────────
+  # The full run-up. Covered but not the priority focus.
+  - id: "approach"
+    type: "polygon"
+    priority: 1.0
+    grid_step: 0.30
+    vertices:
+      - [1.0, 0.0]    # start bottom-left
+      - [7.0, 0.0]    # end   bottom-right  (junction with turn arm)
+      - [7.0, 1.0]    # end   top-right
+      - [1.0, 1.0]    # start top-left
+    placement:
+      # 3 X positions × 2 Y positions = 6 combos
+      # x_offsets : left end of approach at X = 0, 0.5, 1.0
+      # y_offsets : bottom of approach at  Y = 2.5, 3.0
+      x_offsets: [0.0, 0.5, 1.0]
+      y_offsets: [2.5, 3.0]
+
+  # ── Level 2 : turn arm — left side (toward +Y, 2m × 1.5m) ───────────
+  # The portion of the perpendicular corridor ABOVE the approach axis.
+  # Subject turns left here.
+  - id: "turn_left"
+    type: "polygon"
+    priority: 1.8
+    grid_step: 0.25
+    vertices:
+      - [8.0,  -1.5]  # far end top-left
+      - [10.0, -1.5]  # far end top-right
+      - [10.0,  0.0]  # meets approach top (intersection boundary)
+      - [8.0,   0.0]  # meets approach top (intersection boundary)
+    placement:
+      x_offsets: [0.0, 0.5, 1.0]
+      y_offsets: [2.5, 3.0]
+
+  # ── Level 2 : turn arm — right side (toward -Y, 2m × 1.5m) ──────────
+  # The portion of the perpendicular corridor BELOW the approach axis.
+  # Subject turns right here.
+  - id: "turn_right"
+    type: "polygon"
+    priority: 1.8
+    grid_step: 0.25
+    vertices:
+      - [8.0,  1.0]   # meets approach bottom (intersection boundary)
+      - [10.0, 1.0]   # meets approach bottom (intersection boundary)
+      - [10.0, 2.5]   # far end bottom-right
+      - [8.0,  2.5]   # far end bottom-left
+    placement:
+      x_offsets: [0.0, 0.5, 1.0]
+      y_offsets: [2.5, 3.0]
+
+  # ── Level 3 : intersection (2m × 1m) — maximum priority ──────────────
+  # Where the approach meets the turn arm. The direction change happens
+  # here — maximise camera coverage at all costs.
+  - id: "intersection"
+    type: "polygon"
+    priority: 2.5
+    grid_step: 0.15
+    vertices:
+      - [7.0,  0.0]   # bottom-left  (end of approach / top of right turn)
+      - [10.0, 0.0]   # bottom-right
+      - [10.0, 1.0]   # top-right
+      - [7.0,  1.0]   # top-left
+    placement:
+      x_offsets: [0.0, 0.5, 1.0]
+      y_offsets: [2.5, 3.0]
+
+# ─────────────────────────────────────────────────────────────
+# 6. OPTIMISATION PARAMETERS
+# ─────────────────────────────────────────────────────────────
+optimization:
+  target_coverage: 5
+  bilateral_weight: 0.9
+  vertical_coverage_threshold: 0.9
+  restarts_per_combo: 15
+  wall_step: 0.35
+  angle_steps: 24
+  tripod_grid_step: 0.80
+  distance_quality_factor: 0.005
+  # algo options:
+  #   greedy      → pure greedy (fast, original behaviour)
+  #   greedy_1opt → greedy init + 1-opt local search (better quality, recommended)
+  algo: "greedy_1opt"
+  early_stop: 5   # stop if no improvement after 5 consecutive restarts (0 = auto)
+  graph_mode: "all"
+

lab_camera_optimizer-1.0.2/configs/example_real_world.yaml

@@ -0,0 +1,270 @@
+# =============================================================
+# Lab Camera Optimizer — Real-world example configuration
+# L-shaped room with obstacles, two camera sets, corridor zones.
+# Based on an actual biomechanics lab (13m × 4.7m, L-shaped).
+# Use this as a starting point for complex lab geometries.
+# =============================================================
+# Units : metres for all distances, degrees for all angles.
+# Angles follow the standard mathematical convention:
+#   0° = East (+X), 90° = North (+Y), 180°/-180° = West (-X)
+# =============================================================
+
+# ─────────────────────────────────────────────────────────────
+# 1. ROOM GEOMETRY
+# ─────────────────────────────────────────────────────────────
+room:
+  # List of (X, Y) vertices of the room polygon, in order (CW or CCW).
+  # The room is assumed to be a flat floor plan.
+  corners:
+    - [0,   0  ]
+    - [13,  0  ]
+    - [13,  3.0]
+    - [8,   3.0]
+    - [8,   4.7]
+    - [0,   4.7]
+
+  # Floor-to-ceiling height (metres)
+  height: 3.0
+
+
+# ─────────────────────────────────────────────────────────────
+# 2. OBSTACLES
+# ─────────────────────────────────────────────────────────────
+# Two types supported:
+#
+#   type: rect    → axis-aligned rectangle
+#                   bounds: [x_min, y_min, x_max, y_max]
+#
+#   type: polygon → arbitrary polygon
+#                   vertices: [[x0,y0],[x1,y1],...]  (in order)
+#
+# height: floor-to-ceiling height of the obstacle (metres).
+#   = room.height  → fully blocks line-of-sight (wall/pillar)
+#   < room.height  → partial height (object, furniture)
+#                    does NOT block line-of-sight above it
+#
+# can_mount_camera: true → wall cameras can be placed on this surface
+#                   false (default) → no camera on this obstacle
+
+obstacles:
+  - type: rect
+    bounds: [1.70, 0.00, 2.04, 0.34]
+    height: 3.0
+    label: "Stub 1"
+    can_mount_camera: true
+
+  - type: rect
+    bounds: [5.39, 0.00, 5.59, 0.42]
+    height: 3.0
+    label: "Stub 2"
+    can_mount_camera: true
+
+  - type: rect
+    bounds: [8.94, 0.00, 9.14, 0.42]
+    height: 3.0
+    label: "Stub 3"
+    can_mount_camera: true
+
+  - type: rect
+    bounds: [5.65, 3.85, 5.85, 4.25]
+    height: 3.0
+    label: "Stub 4"
+    can_mount_camera: true
+
+  - type: rect
+    bounds: [5.65, 2.85, 6.35, 3.55]
+    height: 1.4
+    label: "Object 1"
+    can_mount_camera: false   # partial-height object, no camera mount
+
+  - type: polygon
+    vertices:
+      - [1.47, 4.70]
+      - [1.47, 4.38]
+      - [1.71, 4.38]
+      - [1.71, 3.88]
+      - [2.04, 3.88]
+      - [2.04, 4.27]
+      - [3.02, 4.27]
+      - [3.02, 4.70]
+    height: 3.0
+    label: "Wall N"
+    can_mount_camera: true
+
+
+# ─────────────────────────────────────────────────────────────
+# 3. SUBJECT (person being recorded)
+# ─────────────────────────────────────────────────────────────
+subject:
+  height: 1.9              # total height feet-to-head (metres)
+  foot_z: 0.0              # height of feet above floor (metres, usually 0)
+
+
+# ─────────────────────────────────────────────────────────────
+# 4. CAMERA SETS
+# ─────────────────────────────────────────────────────────────
+# Define as many camera sets as needed.
+# Each set is an independent group of cameras with its own FOV,
+# mounting type, placement constraints and score weight.
+#
+# mounting:
+#   wall    → cameras placed on room walls and floor-to-ceiling obstacles
+#   tripod  → cameras placed freely inside the room on a tripod stand
+#   ceiling → (future) cameras hung from the ceiling
+#
+# optional: true → this entire set is skipped if max_count is 0
+
+camera_sets:
+
+  - id: "cam_A"
+    name: "ZED2i"
+    mounting: "wall"
+    optional: false
+
+    # Field of view (degrees) — landscape and portrait orientations
+    fov_h_landscape: 110.0
+    fov_v_landscape:  70.0
+    fov_h_portrait:   70.0
+    fov_v_portrait:  110.0
+
+    # Detection range (metres)
+    max_range: 15.0
+    min_range:  0.5         # blind zone closer than this
+
+    # Camera heights to evaluate (metres).
+    # Each candidate position is tested at ALL heights listed here.
+    # A single optimised configuration can mix different heights.
+    height_options: [2.0, 2.2]
+
+    # Placement constraints
+    max_count: 10           # maximum number of cameras to place
+    min_spacing: 1.5        # minimum distance between two cameras of this set (m)
+
+    # Score contribution
+    score_weight: 1.0       # relative weight vs other camera sets
+
+    # Visualisation
+    color: "#1f77b4"        # hex colour for graphs
+
+
+  - id: "cam_B"
+    name: "iPad"
+    mounting: "tripod"
+    optional: true          # set max_count: 0 to fully disable
+
+    fov_h_landscape:  80.0
+    fov_v_landscape:  58.0
+    fov_h_portrait:   58.0
+    fov_v_portrait:   80.0
+
+    max_range: 10.0
+    min_range:  0.5
+
+    height_options: [1.5]
+
+    max_count: 2
+    min_spacing: 1.5
+
+    # Tripod-specific: minimum distance from the capture axis (metres).
+    # Prevents the tripod from blocking the walking path.
+    walk_axis_margin: 0.7
+
+    score_weight: 0.6
+
+    color: "#d62728"
+
+
+# ─────────────────────────────────────────────────────────────
+# 5. CAPTURE ZONES
+# ─────────────────────────────────────────────────────────────
+# Zones define WHERE the cameras must provide coverage and HOW MUCH
+# each zone matters (priority weight in the global score).
+#
+# Zone types:
+#   corridor  → rectangular strip, explored at several X/Y positions
+#   sub_zone  → rectangular strip contained within a parent corridor
+#   point     → circular zone (e.g. a chair test)
+#
+# The optimiser tests all combinations of (x_start, y_position, sub_offset)
+# and keeps the globally best placement.
+
+capture_zones:
+
+  # ── Primary corridor (total walking path) ─────────────────
+  - id: "full_corridor"
+    type: "corridor"
+    priority: 0.5           # lower weight: coverage outside analysis is a bonus
+
+    length: 10.0            # length of the corridor (metres, along main axis)
+    width:   1.0            # transverse width of the evaluation strip (metres)
+
+    # Positions to explore during optimisation
+    placement:
+      # X start positions of the corridor to test (metres from room origin)
+      x_start_options: [1.0, 2.0]
+      # Transverse (Y) axis positions of the corridor centre to test
+      y_options: [1.0, 1.4, 1.8]
+
+  # ── Analysis zone (priority sub-zone inside the corridor) ──
+  - id: "analysis_zone"
+    type: "sub_zone"
+    priority: 1.0           # main zone: highest weight on coverage score
+
+    length: 6.0             # length of the priority sub-zone (metres)
+    contained_in: "full_corridor"
+
+    # Offsets (metres) from the corridor start where the sub-zone can begin.
+    # e.g. offset 1.0 → sub-zone starts 1m after corridor start (1m run-up)
+    #      offset 3.0 → sub-zone starts 3m in (3m run-up, 1m deceleration)
+    offset_options: [1.0, 2.0, 3.0]
+
+  # ── STS point (sit-to-stand chair test — secondary priority zone) ──
+  - id: "sts_point"
+    type: "point"
+    priority: 2.0           # highest weight: this spot must be very well covered
+
+    radius: 0.6             # coverage circle radius (metres)
+    contained_in: "analysis_zone"
+
+    # If true, the optimiser searches automatically for the best position
+    # of this point inside the parent zone (maximises camera coverage score).
+    auto_optimize: true
+
+
+# ─────────────────────────────────────────────────────────────
+# 6. OPTIMISATION PARAMETERS
+# ─────────────────────────────────────────────────────────────
+optimization:
+
+  # Number of cameras required per evaluation point to consider it "well covered"
+  target_coverage: 6
+
+  # Bilateral constraint weight [0.0 – 1.0]
+  # 0.0 = disabled (pure coverage maximisation)
+  # 1.0 = fully enforced (score 0 if only one side covered)
+  # Recommended: 0.6 – 0.8 for biomechanics labs
+  bilateral_weight: 0.9
+
+  # Fraction of the subject body (feet→head) that must be visible
+  # for a camera to "count" at an evaluation point.
+  vertical_coverage_threshold: 0.9
+
+  # Greedy optimisation restarts per combination of zone positions
+  restarts_per_combo: 10
+
+  # Candidate generation resolution
+  wall_step: 0.35           # spacing between camera positions along walls (m)
+  angle_steps: 24           # number of yaw angles tested per wall position
+  tripod_grid_step: 0.70    # spacing of the interior tripod grid (m)
+  distance_quality_factor: 0.001
+
+  # Distance quality decay: score multiplier = 1 / (1 + k * d²)
+  # Higher k → strong penalty for distant cameras
+  # k=0.01: 0.96 @ 2m | 0.80 @ 5m | 0.50 @ 10m
+  # Graph generation mode:
+  #   all            → save a graph for every optimisation attempt (verbose)
+  #   records_only   → save only when a new global record is set
+  #   best_per_combo → save only the best result of each zone combination
+  algo: "greedy_1opt"   # greedy | greedy_1opt
+  graph_mode: "all"
+