Merge pull request #3 from sashakolpakov/1-add-features-other-than-coordinates

1 add features other than coordinates

Author: sashakolpakov

.github/workflows/deploy_docs.yml

@@ -29,7 +29,7 @@ jobs:
       run: |
         cd einit_docs
         sphinx-build -b html . _build/html
-    
+
     - name: Deploy to GitHub Pages
       uses: peaceiris/actions-gh-pages@v3
       if: github.ref == 'refs/heads/main'

.github/workflows/pylint.yml

@@ -52,3 +52,4 @@ jobs:
       run: |
         pytest einit_tests/test_einit.py -v
         pytest einit_tests/test_integration.py -v
+        pytest einit_tests/test_features.py -v

README.md

@@ -36,9 +36,10 @@
 
 - **Fast**: < 1ms for 1000 points
 - **Accurate**: Often achieves excellent alignment without iterative refinement
-- **OpenCV compatible**: Returns standard 4×4 transformation matrices  
+- **OpenCV compatible**: Returns standard 4×4 transformation matrices
 - **Robust**: Handles noise, partial overlap, and permuted point clouds
 - **Permutation invariant**: Results are identical regardless of point ordering
+- **Feature-augmented**: Optional per-point features (RGB, intensity, normals) break geometric degeneracy for symmetric shapes
 - **Configurable**: Adjustable parameters for different use cases
 - **Simple API**: One function call to get results
 
@@ -60,9 +61,20 @@ print(T)  # 4x4 homogeneous transformation matrix
 T = register_ellipsoid(
     src_points, dst_points,
     max_correspondence_distance=0.1,  # Maximum distance for valid correspondences
-    min_inlier_fraction=0.7,          # Require 70% valid correspondences  
+    min_inlier_fraction=0.7,          # Require 70% valid correspondences
     leafsize=8                        # Smaller KD-tree leaf size
 )
+
+# With per-point features (e.g. RGB colour or LiDAR intensity)
+# Features break geometric degeneracy for symmetric shapes (spheres, cubes)
+src_rgb = np.random.rand(1000, 3)   # RGB colour per point
+dst_rgb = np.random.rand(1000, 3)
+T = register_ellipsoid(
+    src_points, dst_points,
+    src_features=src_rgb,
+    dst_features=dst_rgb,
+    feature_weight=1.0               # 0.0 = geometry only; typical range 0.1–1.0
+)
 ```
 
 ## Installation
@@ -109,13 +121,21 @@ Real-world performance on test datasets:
 The algorithm works by:
 
 1. **Centering** point clouds at their centroids
-2. **Computing** ellipsoids of inertia via eigendecomposition  
+2. **Computing** ellipsoids of inertia via eigendecomposition (optionally augmented with per-point features)
 3. **Searching** through 8 reflection combinations using KD-tree correspondence recovery
 4. **Filtering** correspondences by distance and inlier fraction
 5. **Returning** a 4×4 transformation matrix
 
 KD-tree correspondence recovery makes the algorithm robust to point cloud permutations, partial overlaps, and outliers without assuming that points at the same array indices correspond to each other.
 
+When per-point features are supplied (`src_features`, `dst_features`, `feature_weight > 0`), the spatial covariance is augmented by a spatial-feature cross-covariance term:
+
+```
+E_aug = P^T P  +  feature_weight * trace_ratio * (P^T F)(P^T F)^T
+```
+
+This biases the principal axes toward directions where features vary most, breaking eigenvalue degeneracy for symmetric shapes (spheres, cubes, cylinders). The KD-tree step also runs in feature-augmented space so that feature similarity guides nearest-neighbour selection. Features are normalised to keep `feature_weight` dimensionless and dataset-independent.
+
 ## OpenCV Integration
 
 ```python
@@ -166,25 +186,32 @@ python einit_examples/bbox_overlap_test.py
 ```
 Evaluates performance on the Stanford bunny with geometric bounding box constraints.
 
-> **Note**: Unlike randomized overlaps, this is a known failure mode of the algorithm. Low success rate is expected. 
+> **Note**: Unlike randomized overlaps, this is a known failure mode of the algorithm. Low success rate is expected.
 
+**Feature Matching Diagnostic:**
+```bash
+python einit_examples/cube_feature_matching.py
+```
+Four-panel diagnostic visualisation showing how RGB face colours break the cube's 48-fold geometric symmetry. Produces eigenvalue spectra, per-candidate RMSE/inlier plots, and side-by-side alignment results comparing geometry-only vs feature-augmented registration.
 
 ### Running Tests
 
+The `einit_tests/` directory contains comprehensive test suites validating core functionality:
+
 ```bash
 # All tests
 pytest einit_tests/ -v
 
-# Core algorithm tests  
-pytest einit_tests/test_einit.py -v
-
-# Stanford bunny integration test
-pytest einit_tests/test_integration.py -v
+# Specific test categories
+pytest einit_tests/test_einit.py -v              # Core algorithm tests
+pytest einit_tests/test_integration.py -v        # Integration and robustness tests
+pytest einit_tests/test_features.py -v           # Feature-augmented benchmarks
 ```
 
 **Test Coverage:**
-- **Core Tests**: Basic functionality, synthetic shapes (spheres, cube surfaces), and Stanford bunny validation
-- **Integration Test**: Real-world Stanford bunny PLY dataset with partial overlap and noise
+- **Core Algorithm Tests** (`test_einit.py`): Basic functionality, permutation invariance, noise robustness, and Stanford bunny dataset validation
+- **Integration Tests** (`test_integration.py`): End-to-end pipeline testing with real-world scenarios
+- **Feature Tests** (`test_features.py`): Three real-world feature scenarios (Stanford bunny with LiDAR intensity, hemisphere-flip sphere, coloured cube), a feature-weight sweep, and API-level validation tests
 
 ## Documentation
 

build/.DS_Store

@@ -0,0 +1,24 @@
+Metadata-Version: 2.1
+Name: einit
+Version: 0.1.0
+Summary: Ellipsoid ICP initialization for OpenCV-compatible pipelines
+Author: Alexander Kolpakov (UATX), Michael Werman (HUJI), Judah Levin (UATX)
+Requires-Python: >=3.6
+License-File: LICENSE
+Requires-Dist: numpy>=1.15
+Requires-Dist: scipy>=1.0
+Provides-Extra: opencv
+Requires-Dist: opencv-python-headless>=3.4; extra == "opencv"
+Provides-Extra: test
+Requires-Dist: pytest>=6.0; extra == "test"
+Requires-Dist: opencv-python-headless>=3.4; extra == "test"
+Requires-Dist: matplotlib>=3.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0; extra == "docs"
+Requires-Dist: sphinx_rtd_theme>=1.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: opencv-python-headless>=3.4; extra == "all"
+Requires-Dist: pytest>=6.0; extra == "all"
+Requires-Dist: matplotlib>=3.0; extra == "all"
+Requires-Dist: sphinx>=4.0; extra == "all"
+Requires-Dist: sphinx_rtd_theme>=1.0; extra == "all"

dist/einit-0.2.0-py3.8.egg

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+setup.py
+einit/__init__.py
+einit/einit.py
+einit.egg-info/PKG-INFO
+einit.egg-info/SOURCES.txt
+einit.egg-info/dependency_links.txt
+einit.egg-info/requires.txt
+einit.egg-info/top_level.txt
+einit_tests/__init__.py
+einit_tests/test_einit.py
+einit_tests/test_features.py
+einit_tests/test_integration.py

einit.egg-info/PKG-INFO

@@ -0,0 +1 @@
+

einit.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+numpy>=1.15
+scipy>=1.0
+
+[all]
+opencv-python-headless>=3.4
+pytest>=6.0
+matplotlib>=3.0
+sphinx>=4.0
+sphinx_rtd_theme>=1.0
+
+[docs]
+sphinx>=4.0
+sphinx_rtd_theme>=1.0
+
+[opencv]
+opencv-python-headless>=3.4
+
+[test]
+pytest>=6.0
+opencv-python-headless>=3.4
+matplotlib>=3.0

einit.egg-info/dependency_links.txt

@@ -0,0 +1,2 @@
+einit
+einit_tests