| """Structured accessibility geometry constraints for 3D amodal completion. |
| |
| The functions in this module convert the deterministic outputs of |
| ``accessibilityamodal.reconstruct`` into a JSON-ready report. The report is intended for |
| navigation-risk review and downstream reconstruction code, not for visual |
| plausibility scoring. |
| """ |
|
|
| from __future__ import annotations |
|
|
| from typing import Any |
|
|
| import cv2 |
| import numpy as np |
|
|
|
|
| VALID_CATEGORIES = { |
| "stairs", |
| "ramp", |
| "walkway", |
| "curb_cut", |
| "raised_curb", |
| "tactile_paving", |
| "unknown", |
| } |
| CONTINUOUS_CATEGORIES = {"ramp", "walkway", "curb_cut", "raised_curb", "tactile_paving"} |
|
|
|
|
| def _round(value: float | int | None, digits: int = 6) -> float | None: |
| if value is None: |
| return None |
| return round(float(value), digits) |
|
|
|
|
| def _ratio(numerator: int | float, denominator: int | float) -> float: |
| if denominator <= 0: |
| return 0.0 |
| return float(numerator) / float(denominator) |
|
|
|
|
| def normalize_category(category: str | None, geometry_mode: str) -> str: |
| value = (category or "").strip().lower() |
| if value == "walkable": |
| value = "walkway" |
| if value in VALID_CATEGORIES: |
| return value |
| if geometry_mode == "stairs": |
| return "stairs" |
| if geometry_mode == "ramp": |
| return "ramp" |
| if geometry_mode == "walkable": |
| return "walkway" |
| return "unknown" |
|
|
|
|
| def _step_interval_consistency(edges_y: list[int]) -> str: |
| if len(edges_y) < 3: |
| return "unknown" |
| gaps = np.diff(np.array(sorted(edges_y), dtype=np.float32)) |
| mean_gap = float(np.mean(gaps)) |
| if mean_gap <= 1e-6: |
| return "unknown" |
| variation = float(np.std(gaps) / mean_gap) |
| if variation < 0.18: |
| return "high" |
| if variation < 0.35: |
| return "medium" |
| return "low" |
|
|
|
|
| def _slope_direction_from_depth(depth: np.ndarray, target: np.ndarray) -> str: |
| if not np.any(target): |
| return "unknown" |
| valid = target & np.isfinite(depth) & (depth > 0) |
| if int(valid.sum()) < 32: |
| return "unknown" |
| ys = np.where(valid)[0] |
| middle = float(np.median(ys)) |
| upper = valid & (np.indices(valid.shape)[0] <= middle) |
| lower = valid & (np.indices(valid.shape)[0] > middle) |
| if int(upper.sum()) < 16 or int(lower.sum()) < 16: |
| return "unknown" |
| upper_depth = float(np.median(depth[upper])) |
| lower_depth = float(np.median(depth[lower])) |
| scale = max(abs(upper_depth), abs(lower_depth), 1e-6) |
| if abs(upper_depth - lower_depth) / scale < 0.02: |
| return "unknown" |
| return "away_from_camera" if upper_depth > lower_depth else "toward_camera" |
|
|
|
|
| def _visible_evidence( |
| category: str, |
| visible_mask: np.ndarray, |
| amodal_mask: np.ndarray, |
| hidden_mask: np.ndarray, |
| obstacle_mask: np.ndarray, |
| depth: np.ndarray, |
| edges_y: list[int], |
| stair_edge_confidence: float, |
| stair_edge_coverage: float, |
| completion_method: str, |
| ) -> list[dict[str, Any]]: |
| evidence: list[dict[str, Any]] = [] |
| amodal_area = int(amodal_mask.sum()) |
| visible_area = int(visible_mask.sum()) |
| hidden_area = int(hidden_mask.sum()) |
| obstacle_overlap = int((obstacle_mask & amodal_mask).sum()) |
|
|
| if visible_area > 0: |
| evidence.append( |
| { |
| "type": "boundary", |
| "description": "visible target mask defines the observed support boundary", |
| "confidence": _round(min(0.95, 0.35 + 0.60 * _ratio(visible_area, max(amodal_area, 1)))), |
| } |
| ) |
|
|
| if hidden_area > 0 or obstacle_overlap > 0: |
| evidence.append( |
| { |
| "type": "occlusion", |
| "description": "hidden target support is constrained by amodal-minus-visible and obstacle overlap", |
| "confidence": _round(min(0.95, 0.30 + 0.60 * _ratio(obstacle_overlap, max(hidden_area, 1)))), |
| } |
| ) |
|
|
| if category == "stairs" and edges_y: |
| evidence.append( |
| { |
| "type": "repeated_step", |
| "description": f"{len(edges_y)} candidate stair tread/riser boundary rows detected", |
| "confidence": _round(max(stair_edge_confidence, min(stair_edge_coverage, 1.0) * 0.75)), |
| } |
| ) |
|
|
| if category in CONTINUOUS_CATEGORIES and "plane" in completion_method: |
| evidence.append( |
| { |
| "type": ( |
| "slope" |
| if category == "ramp" |
| else "curb_boundary" |
| if category == "raised_curb" |
| else "boundary" |
| ), |
| "description": ( |
| "visible curb support is completed as one continuous surface without repeated steps" |
| if category == "raised_curb" |
| else "visible support is completed with a robust continuous-surface prior" |
| ), |
| "confidence": 0.70, |
| } |
| ) |
|
|
| valid_depth = amodal_mask & np.isfinite(depth) & (depth > 0) |
| if int(valid_depth.sum()) >= 128: |
| rows = np.where(valid_depth)[0] |
| row_span = max(int(rows.max() - rows.min()), 1) |
| depth_values = depth[valid_depth] |
| depth_span = float(np.percentile(depth_values, 90) - np.percentile(depth_values, 10)) |
| scale = max(float(np.median(depth_values)), 1e-6) |
| if depth_span / scale > 0.02 and row_span > 8: |
| evidence.append( |
| { |
| "type": "depth_gradient", |
| "description": "target depth varies coherently across the support region", |
| "confidence": _round(min(0.80, depth_span / scale)), |
| } |
| ) |
| return evidence |
|
|
|
|
| def _connected_hidden_regions( |
| category: str, |
| hidden_mask: np.ndarray, |
| completion_method: str, |
| mean_hidden_confidence: float, |
| edges_y: list[int], |
| ) -> list[dict[str, Any]]: |
| if not np.any(hidden_mask): |
| return [] |
| labels_count, labels, stats, _ = cv2.connectedComponentsWithStats( |
| hidden_mask.astype(np.uint8), connectivity=8 |
| ) |
| regions: list[dict[str, Any]] = [] |
| areas = [ |
| (idx, int(stats[idx, cv2.CC_STAT_AREA])) |
| for idx in range(1, labels_count) |
| if int(stats[idx, cv2.CC_STAT_AREA]) > 0 |
| ] |
| areas.sort(key=lambda item: item[1], reverse=True) |
| total = max(int(hidden_mask.sum()), 1) |
| for serial, (idx, area) in enumerate(areas[:12], start=1): |
| if category == "stairs" and len(edges_y) >= 2: |
| basis = "repeated_steps" |
| description = "complete the hidden support by repeating the visible tread/riser pattern" |
| elif category in {"ramp", "walkway", "curb_cut", "raised_curb"} and "plane" in completion_method: |
| basis = "plane_continuity" |
| description = ( |
| "continue one curb top/face support through the hidden region without stair bands" |
| if category == "raised_curb" |
| else "project hidden pixels onto the fitted visible support plane" |
| ) |
| elif category == "tactile_paving": |
| basis = "boundary_continuity" |
| description = "preserve the narrow tactile strip footprint through the hidden region" |
| elif "inpaint" in completion_method: |
| basis = "depth_interpolation" |
| description = "use local depth interpolation because stronger structural evidence is unavailable" |
| else: |
| basis = "uncertain" |
| description = "insufficient structural evidence for confident hidden completion" |
| regions.append( |
| { |
| "region_id": f"hidden_{serial}", |
| "completion_basis": basis, |
| "description": description, |
| "confidence": _round(min(0.95, mean_hidden_confidence * (0.50 + 0.50 * area / total))), |
| } |
| ) |
| return regions |
|
|
|
|
| def _amodal_quality( |
| target_present: bool, |
| visible_mask: np.ndarray, |
| amodal_mask: np.ndarray, |
| hidden_mask: np.ndarray, |
| mean_hidden_confidence: float, |
| used_regular_fallback_edges: bool, |
| ) -> str: |
| if not target_present: |
| return "bad" |
| amodal_area = int(amodal_mask.sum()) |
| visible_ratio = _ratio(int(visible_mask.sum()), amodal_area) |
| hidden_ratio = _ratio(int(hidden_mask.sum()), amodal_area) |
| if visible_ratio < 0.02: |
| return "bad" |
| if used_regular_fallback_edges or mean_hidden_confidence < 0.30: |
| return "uncertain" |
| if visible_ratio >= 0.20 and (hidden_ratio == 0.0 or mean_hidden_confidence >= 0.50): |
| return "good" |
| if visible_ratio >= 0.05: |
| return "partial" |
| return "uncertain" |
|
|
|
|
| def _geometry_model_type(category: str, geometry_mode: str) -> str: |
| if category == "raised_curb": |
| return "raised_curb_prism" |
| if category == "stairs" or geometry_mode == "stairs": |
| return "stair_steps" |
| if category == "curb_cut": |
| return "curb_cut_planes" |
| if category == "tactile_paving": |
| return "tactile_strip" |
| if category in {"ramp", "walkway"}: |
| return "single_plane" |
| return "uncertain" |
|
|
|
|
| def _hidden_depth_rule(category: str, completion_method: str) -> str: |
| if category == "stairs": |
| return "repeat_stair_geometry" |
| if category in {"ramp", "walkway", "curb_cut", "raised_curb", "tactile_paving"} and "plane" in completion_method: |
| return "fit_to_plane" |
| if "inpaint" in completion_method: |
| return "interpolate_between_boundaries" |
| return "uncertain" |
|
|
|
|
| def _recommended_action(category: str, geometry_confidence: float) -> tuple[str, str]: |
| if geometry_confidence < 0.30: |
| return "manual_review", "Evidence is weak; do not generate a navigation mesh without review." |
| if category == "stairs": |
| return ( |
| "stair_regularization", |
| "Fit repeated tread/riser bands and complete hidden depth by stair periodicity.", |
| ) |
| if category == "curb_cut": |
| return ( |
| "curb_cut_plane_decomposition", |
| "Decompose sidewalk, road, and sloped transition planes before meshing.", |
| ) |
| if category == "raised_curb": |
| return ( |
| "raised_curb_prism_fit", |
| "Fit one continuous curb top and vertical face, then extrude a solid prism without repeated stair bands.", |
| ) |
| if category == "tactile_paving": |
| return ( |
| "tactile_centerline_completion", |
| "Keep a narrow tactile strip, continue its centerline, and avoid expanding to the full sidewalk.", |
| ) |
| if category in {"ramp", "walkway"}: |
| return ( |
| "plane_fit", |
| "Fit visible support only, reject obstacle/depth outliers, and project hidden pixels to the plane.", |
| ) |
| return "manual_review", "Unknown category; keep the sample out of automatic 3D completion." |
|
|
|
|
| def build_accessibility_geometry_analysis( |
| *, |
| sample_id: str | None, |
| category: str | None, |
| geometry_mode: str, |
| visible_mask: np.ndarray, |
| amodal_mask: np.ndarray, |
| hidden_mask: np.ndarray, |
| obstacle_mask: np.ndarray, |
| depth: np.ndarray, |
| completed_depth: np.ndarray, |
| confidence: np.ndarray, |
| completion_method: str, |
| edges_y: list[int], |
| stair_edge_slope: float, |
| edge_source: str, |
| stair_edge_confidence: float, |
| stair_edge_coverage: float, |
| used_regular_fallback_edges: bool, |
| visible_depth_unchanged: bool, |
| completed_target_depth_finite: bool, |
| point_cloud_vertices: int, |
| mesh_vertices: int, |
| mesh_faces: int, |
| ) -> dict[str, Any]: |
| """Build the JSON-ready geometry constraint report.""" |
|
|
| normalized_category = normalize_category(category, geometry_mode) |
| target_present = bool(np.any(amodal_mask) or np.any(visible_mask)) |
| hidden_nonempty = bool(np.any(hidden_mask)) |
| hidden_confidence_values = confidence[hidden_mask] if hidden_nonempty else np.array([1.0], dtype=np.float32) |
| mean_hidden_confidence = float(np.mean(hidden_confidence_values)) if hidden_confidence_values.size else 0.0 |
| visible_area = int(visible_mask.sum()) |
| amodal_area = int(amodal_mask.sum()) |
| hidden_area = int(hidden_mask.sum()) |
| obstacle_area = int(obstacle_mask.sum()) |
| obstacle_target_overlap = int((obstacle_mask & amodal_mask).sum()) |
| obstacle_visible_overlap_ratio = _ratio(int((obstacle_mask & visible_mask).sum()), max(visible_area, 1)) |
|
|
| if normalized_category == "stairs": |
| structure_confidence = float(stair_edge_confidence) |
| if used_regular_fallback_edges: |
| structure_confidence = min(structure_confidence, 0.30) |
| elif normalized_category in CONTINUOUS_CATEGORIES: |
| structure_confidence = 0.72 if "plane" in completion_method else 0.38 |
| else: |
| structure_confidence = 0.20 |
|
|
| target_evidence_score = min(1.0, 0.25 + 0.75 * _ratio(visible_area, max(amodal_area, 1))) |
| mesh_score = 1.0 if point_cloud_vertices > 0 and mesh_vertices > 0 and mesh_faces > 0 else 0.25 |
| geometry_confidence = min( |
| 0.99, |
| max( |
| 0.0, |
| 0.35 * structure_confidence |
| + 0.25 * mean_hidden_confidence |
| + 0.20 * target_evidence_score |
| + 0.20 * mesh_score, |
| ), |
| ) |
| if not target_present: |
| geometry_confidence = 0.0 |
| if not completed_target_depth_finite: |
| geometry_confidence *= 0.50 |
|
|
| amodal_quality = _amodal_quality( |
| target_present, |
| visible_mask, |
| amodal_mask, |
| hidden_mask, |
| mean_hidden_confidence, |
| used_regular_fallback_edges, |
| ) |
| if amodal_quality in {"uncertain", "bad"}: |
| geometry_confidence = min(geometry_confidence, 0.55 if amodal_quality == "uncertain" else 0.20) |
|
|
| visible_evidence = _visible_evidence( |
| normalized_category, |
| visible_mask, |
| amodal_mask, |
| hidden_mask, |
| obstacle_mask, |
| depth, |
| edges_y, |
| stair_edge_confidence, |
| stair_edge_coverage, |
| completion_method, |
| ) |
|
|
| occluders = [] |
| if obstacle_area > 0: |
| occluders.append( |
| { |
| "class": "other", |
| "overlaps_target": bool(obstacle_target_overlap > 0), |
| "should_exclude_from_mesh": True, |
| "description": ( |
| "aggregate obstacle mask overlaps the target support" |
| if obstacle_target_overlap > 0 |
| else "aggregate obstacle mask is outside the target support" |
| ), |
| } |
| ) |
|
|
| hidden_regions = _connected_hidden_regions( |
| normalized_category, |
| hidden_mask, |
| completion_method, |
| mean_hidden_confidence, |
| edges_y, |
| ) |
|
|
| plane_applies = normalized_category in CONTINUOUS_CATEGORIES |
| stair_applies = normalized_category == "stairs" |
| model_type = _geometry_model_type(normalized_category, geometry_mode) |
| slope_direction = _slope_direction_from_depth(completed_depth, amodal_mask) |
| expected_surface = ( |
| "segmented" |
| if normalized_category in {"stairs", "curb_cut"} |
| else "continuous_top_with_vertical_face" |
| if normalized_category == "raised_curb" |
| else "sloped" |
| if normalized_category == "ramp" |
| else "flat" |
| if normalized_category in {"walkway", "tactile_paving"} |
| else "segmented" |
| ) |
| hidden_depth_rule = _hidden_depth_rule(normalized_category, completion_method) |
| step_lines = [ |
| { |
| "y": int(y), |
| "slope": _round(stair_edge_slope), |
| "source": edge_source, |
| } |
| for y in edges_y |
| ] |
|
|
| if normalized_category == "stairs": |
| passable = False |
| risk_level = "high" if geometry_confidence >= 0.30 else "unknown" |
| risks = ["stairs present", "wheeled passability is blocked or requires alternate route"] |
| if used_regular_fallback_edges: |
| risks.append("stair geometry relies on fallback edge positions") |
| reason_short = "Stair geometry is detected; treat as high risk for wheeled accessibility." |
| elif normalized_category == "raised_curb": |
| passable = False |
| risk_level = "high" if geometry_confidence >= 0.30 else "unknown" |
| risks = [ |
| "raised curb is a non-walkable level-change barrier", |
| "wheeled passability is blocked or requires a curb cut or alternate route", |
| ] |
| reason_short = "A raised curb is present; model it as a continuous high obstacle, not as stairs." |
| elif geometry_confidence < 0.30 or amodal_quality in {"uncertain", "bad"}: |
| passable = False |
| risk_level = "unknown" |
| risks = ["hidden support geometry is uncertain"] |
| reason_short = "Evidence is insufficient for an automatic passability decision." |
| else: |
| obstacle_intrusion = _ratio(obstacle_target_overlap, max(amodal_area, 1)) |
| passable = obstacle_intrusion < 0.25 and visible_depth_unchanged |
| risk_level = "medium" if hidden_nonempty or obstacle_intrusion > 0.10 else "low" |
| risks = [] |
| if hidden_nonempty: |
| risks.append("hidden region may contain unresolved hazards") |
| if obstacle_intrusion > 0.10: |
| risks.append("obstacle intrudes into the target support") |
| if not risks: |
| risks.append("no major geometry risk from available masks") |
| reason_short = "Continuous support appears geometrically consistent, but monocular depth is not metric truth." |
|
|
| triangle_fan_passed = True |
| if normalized_category in CONTINUOUS_CATEGORIES: |
| triangle_fan_passed = bool(mesh_faces > 0 and ("plane" in completion_method or "continuous" in completion_method)) |
| stair_not_smoothed_passed = True |
| if normalized_category == "stairs": |
| stair_not_smoothed_passed = bool( |
| "stair" in completion_method and len(edges_y) >= 2 and stair_edge_confidence > 0.0 |
| ) |
| raised_curb_not_stepped_passed = True |
| if normalized_category == "raised_curb": |
| raised_curb_not_stepped_passed = bool( |
| geometry_mode != "stairs" and "stair" not in completion_method and not edges_y |
| ) |
| obstacle_exclusion_passed = obstacle_visible_overlap_ratio <= 0.02 |
| hidden_follows_amodal = bool(np.array_equal(hidden_mask, amodal_mask & ~visible_mask)) |
|
|
| next_step, instruction = _recommended_action(normalized_category, geometry_confidence) |
|
|
| return { |
| "sample_id": sample_id or "", |
| "category": normalized_category, |
| "target_present": target_present, |
| "geometry_confidence": _round(geometry_confidence), |
| "visible_evidence": visible_evidence, |
| "occluders": occluders, |
| "amodal_completion": { |
| "target_amodal_region_quality": amodal_quality, |
| "hidden_regions": hidden_regions, |
| "do_not_complete_regions": [ |
| { |
| "description": "obstacle mask outside the hidden target support", |
| "reason": "foreground occluder geometry is not part of the accessible support surface", |
| }, |
| { |
| "description": "outside target_amodal mask", |
| "reason": "completion must be clipped to reviewed or inferred target support", |
| }, |
| { |
| "description": "thin mask boundary band, shadows, reflections, and wall/railing regions", |
| "reason": "these pixels are unstable depth or non-walkable geometry", |
| }, |
| ], |
| }, |
| "geometry_prior": { |
| "model_type": model_type, |
| "plane_prior": { |
| "applies": plane_applies, |
| "slope_direction_image": slope_direction, |
| "expected_surface": expected_surface, |
| "fit_visible_only_then_extend_to_hidden": True, |
| "reject_depth_outliers": True, |
| }, |
| "stairs_prior": { |
| "applies": stair_applies, |
| "step_direction_image": slope_direction, |
| "visible_step_lines": step_lines, |
| "estimated_step_count": len(edges_y) + 1 if edges_y else None, |
| "step_interval_consistency": _step_interval_consistency(edges_y), |
| "hidden_completion_rule": "repeat_visible_tread_riser_pattern", |
| }, |
| "curb_cut_prior": { |
| "applies": normalized_category == "curb_cut", |
| "has_sidewalk_plane": None if normalized_category != "curb_cut" else "plane" in completion_method, |
| "has_road_plane": None, |
| "has_sloped_transition": None if normalized_category != "curb_cut" else "plane" in completion_method, |
| "boundary_or_hinge_lines": [], |
| }, |
| "raised_curb_prior": { |
| "applies": normalized_category == "raised_curb", |
| "is_walkable_surface": False if normalized_category == "raised_curb" else None, |
| "hazard_class": "high_obstacle" if normalized_category == "raised_curb" else None, |
| "has_continuous_top_surface": ( |
| None if normalized_category != "raised_curb" else "plane" in completion_method |
| ), |
| "vertical_face_required": True if normalized_category == "raised_curb" else None, |
| "repeated_step_profile_allowed": False if normalized_category == "raised_curb" else None, |
| "boundary_or_hinge_lines": [], |
| }, |
| }, |
| "depth_completion_constraints": { |
| "trusted_depth_regions": [ |
| "visible target surface excluding obstacle and mask boundary noise", |
| ], |
| "untrusted_depth_regions": [ |
| "obstacle mask", |
| "hidden mask raw depth", |
| "thin railings", |
| "mask boundary band", |
| "specular/shadow regions", |
| ], |
| "hidden_depth_rule": hidden_depth_rule, |
| "mesh_generation_rule": ( |
| "fit one continuous curb top, add a vertical face, and forbid repeated stair bands" |
| if normalized_category == "raised_curb" |
| else "clip mesh by target_amodal mask, remove obstacle geometry, regularize hidden region" |
| ), |
| }, |
| "passability_assessment": { |
| "is_likely_passable": passable, |
| "risk_level": risk_level, |
| "risks": risks, |
| "reason_short": reason_short, |
| }, |
| "failure_checks": [ |
| { |
| "check": "ramp_or_walkway_should_not_collapse_into_triangle_fan", |
| "passed": triangle_fan_passed, |
| "fix_if_failed": "use RANSAC plane fitting on visible target and project hidden mask to fitted plane", |
| }, |
| { |
| "check": "stairs_should_not_be_smoothed_into_single_ramp", |
| "passed": stair_not_smoothed_passed, |
| "fix_if_failed": "fit repeated tread/riser geometry", |
| }, |
| { |
| "check": "raised_curb_should_not_use_repeated_stair_bands", |
| "passed": raised_curb_not_stepped_passed, |
| "fix_if_failed": "switch to continuous-surface completion and fit one raised curb prism", |
| }, |
| { |
| "check": "obstacles_should_not_be_included_in_accessible_mesh", |
| "passed": obstacle_exclusion_passed, |
| "fix_if_failed": "subtract obstacle mask before point cloud and mesh creation", |
| }, |
| { |
| "check": "hidden_region_should_follow_amodal_mask_not_visible_mask_only", |
| "passed": hidden_follows_amodal, |
| "fix_if_failed": "use target_amodal and hidden masks as reconstruction constraints", |
| }, |
| ], |
| "recommended_3d_action": { |
| "next_step": next_step, |
| "short_instruction_for_reconstruction_code": instruction, |
| }, |
| } |
|
|
