mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-04-23 04:06:37 +00:00
add features
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,55 @@
|
||||
# Feature: Single Image Alignment
|
||||
|
||||
## Description
|
||||
|
||||
Core UAV-to-satellite cross-view matching for individual frames using LiteSAM. Computes precise GPS coordinates by aligning a pre-rotated UAV image to a georeferenced satellite tile through homography estimation.
|
||||
|
||||
## Component APIs Implemented
|
||||
|
||||
- `align_to_satellite(uav_image, satellite_tile, tile_bounds) -> AlignmentResult`
|
||||
- `compute_homography(uav_image, satellite_tile) -> Optional[np.ndarray]`
|
||||
- `extract_gps_from_alignment(homography, tile_bounds, image_center) -> GPSPoint`
|
||||
- `compute_match_confidence(alignment) -> float`
|
||||
|
||||
## External Tools and Services
|
||||
|
||||
- **LiteSAM**: Cross-view matching model (TAIFormer encoder, CTM correlation)
|
||||
- **opencv-python**: RANSAC homography estimation, image operations
|
||||
- **numpy**: Matrix operations, coordinate transformations
|
||||
|
||||
## Internal Methods
|
||||
|
||||
| Method | Purpose |
|
||||
|--------|---------|
|
||||
| `_extract_features(image)` | Extract multi-scale features using LiteSAM TAIFormer encoder |
|
||||
| `_compute_correspondences(uav_features, sat_features)` | Compute dense correspondence field via CTM |
|
||||
| `_estimate_homography_ransac(correspondences)` | Estimate 3×3 homography using RANSAC |
|
||||
| `_refine_homography(homography, correspondences)` | Non-linear refinement of homography |
|
||||
| `_validate_match(homography, inliers)` | Check inlier count/ratio thresholds |
|
||||
| `_pixel_to_gps(pixel, tile_bounds)` | Convert satellite pixel coordinates to GPS |
|
||||
| `_compute_inlier_ratio(inliers, total)` | Calculate inlier ratio for confidence |
|
||||
| `_compute_spatial_distribution(inliers)` | Assess inlier spatial distribution quality |
|
||||
| `_compute_reprojection_error(homography, correspondences)` | Calculate mean reprojection error |
|
||||
|
||||
## Unit Tests
|
||||
|
||||
1. **Feature extraction**: LiteSAM encoder produces valid feature tensors
|
||||
2. **Correspondence computation**: CTM produces dense correspondence field
|
||||
3. **Homography estimation**: RANSAC returns valid 3×3 matrix for good correspondences
|
||||
4. **Homography estimation failure**: Returns None for insufficient correspondences (<15 inliers)
|
||||
5. **GPS extraction accuracy**: Pixel-to-GPS conversion within expected tolerance
|
||||
6. **Confidence high**: Returns >0.8 for inlier_ratio >0.6, inlier_count >50, MRE <0.5px
|
||||
7. **Confidence medium**: Returns 0.5-0.8 for moderate match quality
|
||||
8. **Confidence low**: Returns <0.5 for poor matches
|
||||
9. **Reprojection error calculation**: Correctly computes mean pixel error
|
||||
10. **Spatial distribution scoring**: Penalizes clustered inliers
|
||||
|
||||
## Integration Tests
|
||||
|
||||
1. **Single tile drift correction**: Load UAV image + satellite tile → align_to_satellite() returns GPS within 20m of ground truth
|
||||
2. **Progressive search (4 tiles)**: align_to_satellite() on 2×2 grid, first 3 fail, 4th succeeds
|
||||
3. **Rotation sensitivity**: Unrotated image (>45°) fails; pre-rotated image succeeds
|
||||
4. **Multi-scale robustness**: Different GSD (UAV 0.1m/px, satellite 0.3m/px) → match succeeds
|
||||
5. **Altitude variation**: UAV at various altitudes (<1km) → consistent GPS accuracy
|
||||
6. **Performance benchmark**: align_to_satellite() completes in ~60ms (TensorRT)
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# Feature: Chunk Alignment
|
||||
|
||||
## Description
|
||||
|
||||
Batch UAV-to-satellite matching that aggregates correspondences from multiple images in a chunk for more robust geo-localization. Handles scenarios where single-image matching fails (featureless terrain, partial occlusions). Returns Sim(3) transform for the entire chunk.
|
||||
|
||||
## Component APIs Implemented
|
||||
|
||||
- `align_chunk_to_satellite(chunk_images, satellite_tile, tile_bounds) -> ChunkAlignmentResult`
|
||||
- `match_chunk_homography(chunk_images, satellite_tile) -> Optional[np.ndarray]`
|
||||
|
||||
## External Tools and Services
|
||||
|
||||
- **LiteSAM**: Cross-view matching model (TAIFormer encoder, CTM correlation)
|
||||
- **opencv-python**: RANSAC homography estimation
|
||||
- **numpy**: Matrix operations, feature aggregation
|
||||
|
||||
## Internal Methods
|
||||
|
||||
| Method | Purpose |
|
||||
|--------|---------|
|
||||
| `_extract_chunk_features(chunk_images)` | Extract features from all chunk images |
|
||||
| `_aggregate_features(features_list)` | Combine features via mean/max pooling |
|
||||
| `_aggregate_correspondences(correspondences_list)` | Merge correspondences from multiple images |
|
||||
| `_estimate_chunk_homography(aggregated_correspondences)` | Estimate homography from aggregate data |
|
||||
| `_compute_sim3_transform(homography, tile_bounds)` | Extract translation, rotation, scale |
|
||||
| `_get_chunk_center_gps(homography, tile_bounds, chunk_images)` | GPS of middle frame center |
|
||||
| `_validate_chunk_match(inliers, confidence)` | Check chunk-specific thresholds (>30 inliers) |
|
||||
|
||||
## Unit Tests
|
||||
|
||||
1. **Feature aggregation**: Mean pooling produces valid combined features
|
||||
2. **Correspondence aggregation**: Merges correspondences from N images correctly
|
||||
3. **Chunk homography estimation**: Returns valid 3×3 matrix for aggregate correspondences
|
||||
4. **Chunk homography failure**: Returns None for insufficient aggregate correspondences
|
||||
5. **Sim(3) extraction**: Correctly decomposes homography into translation, rotation, scale
|
||||
6. **Chunk center GPS**: Returns GPS of middle frame's center pixel
|
||||
7. **Chunk confidence high**: Returns >0.7 for >50 inliers
|
||||
8. **Chunk confidence medium**: Returns 0.5-0.7 for 30-50 inliers
|
||||
9. **Chunk validation**: Rejects matches with <30 inliers
|
||||
|
||||
## Integration Tests
|
||||
|
||||
1. **Chunk LiteSAM matching**: 10 images from plain field → align_chunk_to_satellite() returns GPS within 20m
|
||||
2. **Chunk vs single-image robustness**: Featureless terrain where single-image fails, chunk succeeds
|
||||
3. **Chunk rotation sweeps**: Unknown orientation → try rotations (0°, 30°, ..., 330°) → match at correct angle
|
||||
4. **Sim(3) transform correctness**: Verify transform aligns chunk trajectory to satellite coordinates
|
||||
5. **Multi-scale chunk matching**: GSD mismatch handled correctly
|
||||
6. **Performance benchmark**: 10-image chunk alignment completes within acceptable time
|
||||
7. **Partial occlusion handling**: Some images occluded → chunk still matches successfully
|
||||
|
||||
Reference in New Issue
Block a user