Aislo/B04_PreProcess/B04_PreProcess_Engine_Ground.py

"""B04 지면 필터 오케스트레이션.

구조화된 포인트클라우드(structured.npz)에 대해 grid_min_z/csf/pmf/ransac/ptd/classification
(+ `_refine` 다듬기 판)
필터를 실행하여 지면 마스크 딕셔너리를 만든다. 필터 선택은 config의
source_filters를 따른다.
"""

from pathlib import Path
from typing import Any

import numpy as np

from B04_PreProcess.B04_PreProcess_Engine_Filter_Classification import (
    filter_classification,
    has_classified_coverage,
    has_classified_ground,
)
from B04_PreProcess.B04_PreProcess_Engine_Filter_CSF import filter_csf
from B04_PreProcess.B04_PreProcess_Engine_Filter_Grid import filter_grid_min_z
from B04_PreProcess.B04_PreProcess_Engine_Filter_PMF import filter_pmf
from B04_PreProcess.B04_PreProcess_Engine_Filter_PTD import filter_ptd
from B04_PreProcess.B04_PreProcess_Engine_Filter_RANSAC import filter_ransac
from B04_PreProcess.B04_PreProcess_Engine_Filter_Refine import refine_ground_mask
from config.config_system import SURFACE_AUTO_FALLBACK_FILTER

# 다듬기 판(762) — `{기본 필터}_refine` = 기본 필터 지면점을 SMRF 꼴로 한 번 더 거름
REFINE_SUFFIX = "_refine"
_REFINABLE = ("classification", "ptd")

# 필터 키 → 함수 매핑
_FILTERS = {
    "grid_min_z": filter_grid_min_z,
    "csf": filter_csf,
    "pmf": filter_pmf,
    "ransac": filter_ransac,
    "ptd": filter_ptd,
    "classification": filter_classification,
    "classification_refine": lambda data: refine_ground_mask(
        data["xyz"], filter_classification(data)
    ),
    "ptd_refine": lambda data: refine_ground_mask(data["xyz"], filter_ptd(data)),
}

# LAS에 지면분류가 실제로 들어 있을 때만 쓰는 필터 (미분류 LAS에서는 마스크가 빈다)
_CONDITIONAL_FILTERS = {
    "classification": has_classified_ground,
    "classification_refine": has_classified_ground,
}


def available_filters() -> tuple[str, ...]:
    return tuple(_FILTERS.keys())


def usable_conditional_filters(
    structured_data: dict[str, Any] | np.lib.npyio.NpzFile,
) -> list[str]:
    """이 LAS에서 실제로 쓸 수 있는 조건부 필터를 고른다 (드롭다운 노출용)."""
    return [key for key, is_usable in _CONDITIONAL_FILTERS.items() if is_usable(structured_data)]


def resolve_auto_source_filters(
    structured_data: dict[str, Any] | np.lib.npyio.NpzFile,
    processed_dir: Path | None = None,
) -> list[str]:
    """자동 전처리가 만들 필터를 입력 LAS를 보고 정한다. 첫 항목이 기본 확정값이다.

    업체가 이미 지면을 분류해 놨으면 그것을 기본으로 쓴다 — 계산이 없고 품질도 가장
    안정적이다. **ptd(점진 TIN)는 분류가 있어도 함께 만든다** — 내장 필터 결과를 눈으로
    검증할 수 있어야 하기 때문이다 (2026-09-01 사용자 확정). 분류가 없으면 ptd 하나만 남는다.
    둘 다 다듬기 판(`_refine`)으로 지음 — 업체 분류 + 다듬기 · 점진 TIN + 다듬기(요구 607).
    「분류 있음」 = 비율 문턱 + 덮임(일부만 분류된 LAS 거름) — 자동 고름에만(요구 558).
    """
    usable = usable_conditional_filters(structured_data)
    if usable and not has_classified_coverage(structured_data, processed_dir):
        usable = []
    filters = [*usable[:1], SURFACE_AUTO_FALLBACK_FILTER]
    # 다듬기 기본(요구 607) — 같은 기본 필터에 다듬기를 붙인 판을 지음(바탕 마스크도 저장)
    return [f"{key}{REFINE_SUFFIX}" if key in _REFINABLE else key for key in filters]


def base_filter(filter_key: str) -> str | None:
    """다듬기 판이면 바탕 필터 이름 — 엔진이 바탕 마스크 저장본을 다시 쓰게."""
    base = filter_key.removesuffix(REFINE_SUFFIX)
    return base if base != filter_key and base in _REFINABLE else None


def run_ground_filter(
    filter_key: str,
    structured_data: dict[str, Any] | np.lib.npyio.NpzFile,
    base_mask: np.ndarray | None = None,
) -> np.ndarray:
    """단일 지면 필터를 실행해 불리언 마스크를 반환한다 — 다듬기 판은 `base_mask` 를 다듬음."""
    if filter_key not in _FILTERS:
        raise ValueError(f"알 수 없는 지면 필터입니다: {filter_key}")
    if base_mask is not None and base_filter(filter_key):
        return refine_ground_mask(structured_data["xyz"], base_mask)
    return np.asarray(_FILTERS[filter_key](structured_data), dtype=bool)


def build_ground_masks(
    structured_data: dict[str, Any] | np.lib.npyio.NpzFile,
    filter_keys: tuple[str, ...] | list[str],
) -> dict[str, np.ndarray]:
    """지정한 필터들을 실행해 {filter_key: mask} 딕셔너리를 만든다."""
    masks: dict[str, np.ndarray] = {}
    for filter_key in filter_keys:
        masks[filter_key] = run_ground_filter(filter_key, structured_data)
    return masks


def summarize_masks(
    structured_data: dict[str, Any] | np.lib.npyio.NpzFile,
    masks: dict[str, np.ndarray],
) -> dict[str, dict[str, Any]]:
    """각 필터 마스크의 지면 포인트 수·비율 요약을 만든다."""
    total = int(len(structured_data["xyz"]))
    summary: dict[str, dict[str, Any]] = {}
    for filter_key, mask in masks.items():
        ground = int(np.count_nonzero(mask))
        summary[filter_key] = {
            "ground_point_count": ground,
            "total_point_count": total,
            "ground_ratio": round(ground / total, 4) if total else 0.0,
        }
    return summary