reverse3d 0.5.0__tar.gz → 0.5.2__tar.gz

{reverse3d-0.5.0/reverse3d.egg-info → reverse3d-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reverse3d
-Version: 0.5.0
+Version: 0.5.2
 Summary: AI-agent-ready toolkit for 3D reverse engineering: image analysis, photogrammetry, mesh repair, primitive fitting and headless rendering.
 Author-email: Voxel Enterprise <info@voxel.lat>
 Maintainer-email: Voxel Enterprise <info@voxel.lat>
@@ -425,6 +425,10 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 
 **Formatos:** imágenes `png jpg jpeg tif tiff bmp webp`, y fotos de iPhone `heic heif` (se convierten a JPEG conservando el EXIF) · mallas `stl obj ply glb gltf off` · nubes `ply xyz pcd`.
 
+**Perfiles de escena:** reverse3d predice si las fotos son de un objeto, un personaje, arquitectura o un paisaje (`reverse3d scene detect <carpeta>`) y ajusta la reconstrucción; también puedes elegirlo con `reverse3d auto <carpeta> --scene architecture`.
+
+**¿Cómo tomar las fotos?** Mínimo 20, recomendadas 40-60, en 4 perfiles (anillos a 10-20°, 35-45° y 60-70°, y 4 desde arriba), sin mover el objeto, con luz pareja y sin reflejos. Guía completa: [docs/captura.md](docs/captura.md).
+
 ---
 
 ## Herramientas externas opcionales

{reverse3d-0.5.0 → reverse3d-0.5.2}/README.md

@@ -358,6 +358,10 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 
 **Formatos:** imágenes `png jpg jpeg tif tiff bmp webp`, y fotos de iPhone `heic heif` (se convierten a JPEG conservando el EXIF) · mallas `stl obj ply glb gltf off` · nubes `ply xyz pcd`.
 
+**Perfiles de escena:** reverse3d predice si las fotos son de un objeto, un personaje, arquitectura o un paisaje (`reverse3d scene detect <carpeta>`) y ajusta la reconstrucción; también puedes elegirlo con `reverse3d auto <carpeta> --scene architecture`.
+
+**¿Cómo tomar las fotos?** Mínimo 20, recomendadas 40-60, en 4 perfiles (anillos a 10-20°, 35-45° y 60-70°, y 4 desde arriba), sin mover el objeto, con luz pareja y sin reflejos. Guía completa: [docs/captura.md](docs/captura.md).
+
 ---
 
 ## Herramientas externas opcionales

reverse3d-0.5.2/reverse3d/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.2"

{reverse3d-0.5.0 → reverse3d-0.5.2}/reverse3d/agent/tools.py

@@ -240,6 +240,11 @@ class RunRecipeArgs(_Args):
     force_analysis: bool = Field(
         False, description="photos_to_model: continue even if the photo check fails."
     )
+    scene: Literal["auto", "object", "character", "architecture", "landscape"] = Field(
+        "auto",
+        description="Photo sets: auto predicts it. object=part/product, character=person "
+        "for games, architecture=building/interior, landscape=terrain/drone flight.",
+    )
     overwrite: bool = _OVERWRITE
 
 
@@ -471,6 +476,7 @@ def _run_recipe(a: RunRecipeArgs, s: Settings) -> dict[str, Any]:
             render=a.render,
             quality=a.quality,
             force_analysis=a.force_analysis,
+            scene=a.scene,
             overwrite=a.overwrite,
         ),
     )

{reverse3d-0.5.0 → reverse3d-0.5.2}/reverse3d/autopilot.py

@@ -68,6 +68,14 @@ KIND_LABEL_ES: dict[str, str] = {
 }
 
 _MIN_PHOTOS = 3
+
+#: Capture guide in one sentence (docs/captura.md has the full guide; Studio shows it too).
+CAPTURE_ADVICE_ES = (
+    "Para un modelo 3D completo: 40-60 fotos (mínimo 20) en 4 perfiles: anillo bajo a 10-20° "
+    "(16 fotos), medio a 35-45° (16), alto a 60-70° (12) y 4 desde arriba; con 60-80 % de "
+    "solape, sin mover el objeto, luz pareja y sin reflejos (luces RGB apagadas; en superficies "
+    "brillantes, spray mate o talco). Guía completa: docs/captura.md."
+)
 _ANALYSIS_SIDE = 256
 
 
@@ -149,7 +157,7 @@ def detect_input(path: str | Path) -> Detection:
                 "unknown",
                 None,
                 f"only {len(images)} photos: photogrammetry needs at least {_MIN_PHOTOS} "
-                "(ideally 20-60)",
+                "(ideally 40-60)",
                 str(src),
             )
         return Detection("unknown", None, "no photos, drawings or 3D files in the folder", str(src))
@@ -291,6 +299,8 @@ def _relief_fallback(
 ) -> dict[str, Any]:
     """Photogrammetry was not possible: build an approximate model from the best photo."""
     photo, mask = _best_photo(source, out, settings)
+    if base.scene in ("architecture", "landscape"):
+        mask = None  # an open scene: keep the whole view as a relief
     logger.info("Photogrammetry not possible; building an AI-depth relief from %s", photo.name)
     summary = run_recipe(
         "photo_to_relief",
@@ -344,6 +354,16 @@ def auto_run(
         source = _mesh_from_points(detection, out, settings, base.overwrite)
 
     history: list[dict[str, Any]] = []
+    scene_info: dict[str, Any] | None = None
+    if detection.kind == "photos":
+        from reverse3d.scenes import SCENE_PRESETS, detect_scene
+
+        if base.scene == "auto":
+            predicted = detect_scene(source, settings)
+            scene_info = predicted.to_dict()
+            base = replace(base, scene=predicted.kind)
+        elif base.scene in SCENE_PRESETS:
+            scene_info = {"kind": base.scene, "confidence": 1.0, "reasons": ["chosen"]}
     summary: dict[str, Any] | None = None
     last_error: Reverse3DError | None = None
     capture_advice: list[str] = []
@@ -388,11 +408,14 @@ def auto_run(
 
     if summary is None and detection.kind == "photos" and last_error is not None:
         reason = last_error.message.split(":", 1)[0].rstrip(".")
-        capture_advice = [
-            "Para un modelo 3D completo: 30-60 fotos en orden alrededor del objeto, sin moverlo, "
-            "con luz pareja y sin reflejos (las luces RGB apagadas; en superficies brillantes, "
-            "spray mate o talco).",
-        ]
+        from reverse3d.scenes import scene_advice
+
+        photos = len(
+            list_images(source, max_images=settings.max_images, max_bytes=settings.max_input_bytes)
+        )
+        capture_advice = (
+            scene_advice(base.scene, photos) if base.scene != "auto" else [CAPTURE_ADVICE_ES]
+        )
         try:
             summary = _relief_fallback(source, out, settings, base, reason, history)
         except Reverse3DError as exc:
@@ -405,6 +428,8 @@ def auto_run(
         raise last_error or ProcessingError("No processing attempt could run.")
 
     summary["auto"] = {"detected": detection.to_dict(), "attempts": history}
+    if scene_info is not None:
+        summary["auto"]["scene"] = scene_info
     summary["next_steps"] = capture_advice + next_steps(detection, summary, base)
     summary["outputs"]["summary"] = str(write_summary(out, detection, summary))
     return summary

{reverse3d-0.5.0 → reverse3d-0.5.2}/reverse3d/cli.py

@@ -67,6 +67,10 @@ app.add_typer(vision_app, name="vision")
 app.add_typer(recon_app, name="recon")
 app.add_typer(mesh_app, name="mesh")
 app.add_typer(agent_app, name="agent")
+scene_app = typer.Typer(
+    help="Scene profiles: object, character, architecture, landscape.", no_args_is_help=True
+)
+app.add_typer(scene_app, name="scene")
 
 
 @dataclass
@@ -757,6 +761,10 @@ def auto_cmd(
     units_per_pixel: float | None = typer.Option(None, min=0, help="Drawing scale (mm/px)."),
     scale: float = typer.Option(1.0, min=1e-9, help="Final uniform scale (m→mm: 1000)."),
     render: bool = typer.Option(True, help="Render a PNG preview at the end."),
+    scene: str = typer.Option(
+        "auto",
+        help="Photo sets: auto (predicted), object, character, architecture or landscape.",
+    ),
     force: bool = typer.Option(False, "--force", "-f", help="Overwrite outputs."),
 ) -> None:
     """Detect what INPUT is and process it automatically (no recipe to choose)."""
@@ -769,6 +777,7 @@ def auto_cmd(
         units_per_pixel=units_per_pixel,
         scale=scale,
         render=render,
+        scene=scene,
         overwrite=force,
     )
 
@@ -780,6 +789,22 @@ def auto_cmd(
     _run(ctx, job)
 
 
+@scene_app.command("detect")
+def scene_detect_cmd(
+    ctx: typer.Context,
+    folder: Path = typer.Argument(..., help="Folder with the photos."),
+) -> None:
+    """Predict the scene of a photo set (object, character, architecture, landscape)."""
+    from reverse3d.imaging import prepare_heic_input
+    from reverse3d.scenes import detect_scene
+
+    def job(s: Settings) -> Any:
+        work = s.workspace / ".scene"
+        return detect_scene(prepare_heic_input(folder, work), s).to_dict()
+
+    _run(ctx, job)
+
+
 _WATCH_TEXT = {
     "detected": "📥 Nuevo: {item} (esperando a que termine de copiarse…)",
     "processing": "⚙️  Procesando {item}…",

{reverse3d-0.5.0 → reverse3d-0.5.2}/reverse3d/recipes.py

@@ -73,6 +73,8 @@ class RecipeOptions:
     overwrite: bool = False
     #: plan_to_part: how the drawing is separated from the background.
     mask_method: MaskMethod = "otsu"
+    #: photos_to_model: scene profile (object, character, architecture, landscape) or "auto".
+    scene: str = "auto"
     #: photo_to_relief: object mask (white = keep), e.g. from the autopilot fallback.
     mask_path: str | None = None
     #: mesh repair strength; "strong" closes much larger holes.
@@ -194,8 +196,26 @@ _MIN_GROUP = 8
 
 def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
     from reverse3d.reconstruction.photogrammetry import PhotogrammetryOptions, run_photogrammetry
+    from reverse3d.scenes import SCENE_LABEL_ES, SCENE_PRESETS, detect_scene
     from reverse3d.vision.feature_matcher import analyze_image_set
 
+    scene: str
+    if opt.scene == "auto":
+        detection = run.step("scene", lambda: detect_scene(src, run.settings))
+        scene, confidence, predicted = detection.kind, detection.confidence, True
+    elif opt.scene in SCENE_PRESETS:
+        scene, confidence, predicted = opt.scene, 1.0, False
+    else:
+        raise InputValidationError(
+            f"Unknown scene '{opt.scene}'.", hint=f"Use auto or one of: {', '.join(SCENE_PRESETS)}"
+        )
+    preset = SCENE_PRESETS[scene]
+    run.details["scene"] = {
+        "kind": scene,
+        "label": SCENE_LABEL_ES[scene],
+        "confidence": confidence,
+        "predicted": predicted,
+    }
     analysis = run.step("analyze", lambda: analyze_image_set(src, run.settings))
     run.details["analysis"] = analysis.to_dict()
     if not analysis.suitable_for_photogrammetry and analysis.connected_images >= _MIN_GROUP:
@@ -223,14 +243,20 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
             )
         run.warnings.extend(analysis.recommendations)
 
-    quality = opt.quality or profile_values(run.settings).photo_quality
+    quality = opt.quality or preset.quality or profile_values(run.settings).photo_quality
     photo = run.step(
         "photogrammetry",
         lambda: run_photogrammetry(
             src,
             run.out / "reconstruction",
             run.settings,
-            PhotogrammetryOptions(quality=quality, use_gpu=wants_gpu(run.settings)),  # type: ignore[arg-type]
+            PhotogrammetryOptions(
+                quality=quality,  # type: ignore[arg-type]
+                matcher=preset.matcher,
+                use_gpu=wants_gpu(run.settings),
+                poisson_depth=preset.poisson_depth,
+                density_quantile=preset.density_quantile,
+            ),
             overwrite=opt.overwrite,
         ),
     )
@@ -249,7 +275,8 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
         model,
         scale=opt.scale,
         overwrite=opt.overwrite,
-        keep_largest=True,
+        fill_holes=preset.fill_holes,
+        keep_largest=preset.keep_largest,
         repair=opt.repair,
     )
     return _measure(run, model)
@@ -452,6 +479,8 @@ def run_recipe(
         "steps": [f"{s['step']}:{s['s']}s" for s in run.steps],
         "warnings": run.warnings,
     }
+    if "scene" in run.details:
+        summary["scene"] = run.details["scene"]
     if "primitive_summary" in run.details:
         summary["primitives"] = run.details["primitive_summary"]
 

{reverse3d-0.5.0 → reverse3d-0.5.2}/reverse3d/reconstruction/photogrammetry.py

@@ -46,7 +46,7 @@ from reverse3d.security import (
 logger = logging.getLogger(__name__)
 
 Quality = Literal["low", "medium", "high"]
-MatcherKind = Literal["auto", "exhaustive", "sequential"]
+MatcherKind = Literal["auto", "exhaustive", "sequential", "spatial"]
 DenseMode = Literal["auto", "on", "off"]
 
 CAMERA_MODELS = frozenset(
@@ -82,12 +82,20 @@ class PhotogrammetryOptions:
     camera_model: str = "SIMPLE_RADIAL"
     single_camera: bool = True
     build_mesh: bool = True
+    #: Poisson octree depth; None uses the quality preset (scene profiles raise it).
+    poisson_depth: int | None = None
+    #: share of the least supported surface trimmed after Poisson.
+    density_quantile: float = 0.02
 
     def validate(self) -> None:
         if self.quality not in _PRESETS:
             raise InputValidationError(f"quality must be one of {sorted(_PRESETS)}")
-        if self.matcher not in ("auto", "exhaustive", "sequential"):
-            raise InputValidationError("matcher must be auto, exhaustive or sequential")
+        if self.matcher not in ("auto", "exhaustive", "sequential", "spatial"):
+            raise InputValidationError("matcher must be auto, exhaustive, sequential or spatial")
+        if self.poisson_depth is not None and not 5 <= self.poisson_depth <= 13:
+            raise InputValidationError("poisson_depth must be in [5, 13]")
+        if not 0 <= self.density_quantile < 0.5:
+            raise InputValidationError("density_quantile must be in [0, 0.5)")
         if self.dense not in ("auto", "on", "off"):
             raise InputValidationError("dense must be auto, on or off")
         if self.camera_model not in CAMERA_MODELS:
@@ -296,18 +304,38 @@ class ColmapPipeline:
 
         # 2. Matching
         matcher = options.matcher
+        if matcher == "spatial":
+            from reverse3d.scenes import has_gps
+
+            # GPS-guided matching (drone / large outdoor sets); without GPS, sequential.
+            matcher = "spatial" if has_gps(staged) else "sequential"
         if matcher == "auto":
             matcher = "exhaustive" if len(images) <= _EXHAUSTIVE_LIMIT else "sequential"
         command = f"{matcher}_matcher"
-        self._stage(
-            result,
-            command,
-            self._with_options(
+        extra: dict[tuple[str, ...], str] = {
+            ("FeatureMatching.use_gpu", "SiftMatching.use_gpu"): gpu
+        }
+        if matcher == "spatial":
+            extra[("SpatialMatching.is_gps",)] = "1"
+        try:
+            self._stage(
+                result,
                 command,
-                [command, "--database_path", str(db)],
-                {("FeatureMatching.use_gpu", "SiftMatching.use_gpu"): gpu},
-            ),
-        )
+                self._with_options(command, [command, "--database_path", str(db)], extra),
+            )
+        except ExternalToolError:
+            if matcher != "spatial":
+                raise
+            result.warnings.append("GPS matching failed; used sequential matching instead.")
+            self._stage(
+                result,
+                "sequential_matcher",
+                self._with_options(
+                    "sequential_matcher",
+                    ["sequential_matcher", "--database_path", str(db)],
+                    {("FeatureMatching.use_gpu", "SiftMatching.use_gpu"): gpu},
+                ),
+            )
 
         # 3. Sparse reconstruction (SfM)
         self._stage(
@@ -389,7 +417,8 @@ class ColmapPipeline:
                     cloud,
                     out / "mesh.ply",
                     self.settings,
-                    depth=preset["poisson_depth"],
+                    depth=options.poisson_depth or preset["poisson_depth"],
+                    density_quantile=options.density_quantile,
                     overwrite=True,
                 )
                 result.mesh_path = meshing.mesh_path

reverse3d-0.5.2/reverse3d/scenes.py

@@ -0,0 +1,392 @@
+"""Scene profiles: what kind of capture a photo set is, and how to process it.
+
+reverse3d handles very different captures: a part on a table, a person for a
+game character, a building, or a landscape flown with a drone. They need
+different photogrammetry settings, cleaning and advice. :func:`detect_scene`
+predicts the kind from a quick look at a sample of the photos (EXIF, GPS,
+drone metadata, how isolated the subject is, people, straight lines, sky), and
+:data:`SCENE_PRESETS` holds the settings for each kind.
+
+The prediction is deterministic (plain image statistics, no AI model), so it
+works offline and gives the same answer on every machine. It always returns
+its reasons, so the user can confirm or change it.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import cv2
+import numpy as np
+
+from reverse3d.config import Settings
+from reverse3d.imaging import downscale, load_image
+from reverse3d.security import list_images, validate_input_dir
+
+logger = logging.getLogger(__name__)
+
+SceneKind = Literal["object", "character", "architecture", "landscape"]
+SCENES: tuple[SceneKind, ...] = ("object", "character", "architecture", "landscape")
+
+SCENE_LABEL_ES: dict[str, str] = {
+    "object": "Objeto o pieza",
+    "character": "Personaje o persona",
+    "architecture": "Arquitectura",
+    "landscape": "Paisaje o terreno",
+}
+
+_SAMPLE = 8
+_SIDE = 640
+_DRONE_MAKES = ("dji", "parrot", "autel", "skydio", "yuneec")
+
+
+@dataclass(frozen=True)
+class ScenePreset:
+    """How a scene kind is captured and processed."""
+
+    min_photos: int
+    recommended: tuple[int, int]
+    #: photogrammetry quality; None keeps the hardware profile's choice.
+    quality: Literal["low", "medium", "high"] | None
+    #: "spatial" uses GPS when the photos have it (falls back to sequential).
+    matcher: Literal["auto", "exhaustive", "sequential", "spatial"]
+    poisson_depth: int | None
+    #: share of the least supported surface removed after Poisson (open scenes need more).
+    density_quantile: float
+    #: closed solid (objects) or open surface (buildings, terrain).
+    fill_holes: bool
+    keep_largest: bool
+
+
+SCENE_PRESETS: dict[str, ScenePreset] = {
+    "object": ScenePreset(20, (40, 60), None, "auto", None, 0.02, True, True),
+    "character": ScenePreset(40, (60, 100), "high", "auto", 10, 0.03, True, True),
+    "architecture": ScenePreset(50, (80, 200), None, "auto", 11, 0.05, False, False),
+    "landscape": ScenePreset(60, (100, 400), None, "spatial", 11, 0.06, False, False),
+}
+
+
+@dataclass
+class SceneSignals:
+    """What the photos look like (all shares are 0..1)."""
+
+    photos: int
+    sampled: int
+    gps_photos: int = 0
+    gps_spread_m: float | None = None
+    drone: bool = False
+    nadir_share: float = 0.0
+    isolation: float = 0.0
+    people_share: float = 0.0
+    rectilinear: float = 0.0
+    sky_share: float = 0.0
+    camera: str | None = None
+
+
+@dataclass
+class SceneDetection:
+    """Result of :func:`detect_scene`."""
+
+    kind: SceneKind
+    confidence: float
+    #: short codes the apps translate (drone, gps_wide, nadir, people, isolated_object,
+    #: straight_lines, sky, few_photos).
+    reasons: list[str]
+    scores: dict[str, float]
+    signals: SceneSignals
+    min_photos: int
+    recommended: tuple[int, int]
+    enough_photos: bool
+    advice: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+# ─── EXIF / XMP ───────────────────────────────────────────────────────────────
+
+
+def _rational(value: object) -> float:
+    try:
+        return float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError, ZeroDivisionError):
+        return float("nan")
+
+
+def _gps_degrees(dms: object, ref: object) -> float | None:
+    if not isinstance(dms, (tuple, list)) or len(dms) != 3:
+        return None
+    d, m, s = (_rational(x) for x in dms)
+    if any(math.isnan(x) for x in (d, m, s)):
+        return None
+    value = d + m / 60 + s / 3600
+    return -value if str(ref).upper() in ("S", "W") else value
+
+
+def _photo_metadata(path: Path) -> tuple[str | None, tuple[float, float] | None, float | None]:
+    """(camera "make model", (lat, lon), gimbal pitch in degrees) of one photo."""
+    from PIL import Image
+
+    camera: str | None = None
+    position: tuple[float, float] | None = None
+    pitch: float | None = None
+    try:
+        with Image.open(path) as image:
+            exif = image.getexif()
+            make, model = str(exif.get(271, "")).strip(), str(exif.get(272, "")).strip()
+            camera = f"{make} {model}".strip() or None
+            gps = exif.get_ifd(0x8825)
+            lat = _gps_degrees(gps.get(2), gps.get(1))
+            lon = _gps_degrees(gps.get(4), gps.get(3))
+            if lat is not None and lon is not None and (lat, lon) != (0.0, 0.0):
+                position = (lat, lon)
+    except Exception as exc:  # unreadable metadata is not an error: it is just missing
+        logger.debug("No EXIF in %s: %s", path.name, exc)
+    try:
+        head = path.read_bytes()[:262_144]
+        marker = b'GimbalPitchDegree="'
+        k = head.find(marker)
+        if k >= 0:
+            end = head.find(b'"', k + len(marker))
+            pitch = float(head[k + len(marker) : end].decode("ascii", "ignore"))
+    except (OSError, ValueError):
+        pass
+    return camera, position, pitch
+
+
+def _spread_m(points: list[tuple[float, float]]) -> float | None:
+    """Largest distance between GPS positions, in metres (equirectangular)."""
+    if len(points) < 2:
+        return None
+    lat0 = math.radians(sum(p[0] for p in points) / len(points))
+    xy = np.array([(math.radians(lon) * math.cos(lat0), math.radians(lat)) for lat, lon in points])
+    xy *= 6_371_000.0
+    span = xy.max(axis=0) - xy.min(axis=0)
+    return float(np.hypot(*span))
+
+
+# ─── image statistics ─────────────────────────────────────────────────────────
+
+
+def _rectilinear(gray: np.ndarray) -> float:
+    """How much of the picture is long straight vertical/horizontal edges (buildings)."""
+    edges = cv2.Canny(gray, 60, 160)
+    diag = math.hypot(*gray.shape[:2])
+    lines = cv2.HoughLinesP(edges, 1, np.pi / 180, 60, minLineLength=diag * 0.08, maxLineGap=6)
+    if lines is None:
+        return 0.0
+    total = 0.0
+    straight = 0.0
+    for x1, y1, x2, y2 in np.asarray(lines).reshape(-1, 4):
+        length = math.hypot(x2 - x1, y2 - y1)
+        angle = abs(math.degrees(math.atan2(y2 - y1, x2 - x1))) % 180
+        total += length
+        if min(angle, 180 - angle) < 8 or abs(angle - 90) < 8:
+            straight += length
+    # ~6 picture diagonals of straight lines is already a very rectilinear scene.
+    return float(min(straight / (6 * diag), 1.0)) * (straight / total if total else 0.0)
+
+
+def _sky(bgr: np.ndarray) -> float:
+    """Share of the top third that looks like sky (bright and grey, or blue)."""
+    top = bgr[: bgr.shape[0] // 3]
+    hsv = cv2.cvtColor(top, cv2.COLOR_BGR2HSV)
+    h, s, v = hsv[..., 0], hsv[..., 1], hsv[..., 2]
+    grey_sky = (v > 175) & (s < 45)
+    blue_sky = (h >= 90) & (h <= 130) & (s > 40) & (v > 110)
+    return float((grey_sky | blue_sky).mean())
+
+
+def _looks_like_person(bgr: np.ndarray, mask: np.ndarray) -> bool:
+    """A standing person: an isolated subject clearly taller than wide, with skin.
+
+    A plain-statistics heuristic (no detector model, so it works offline); the
+    apps always let the user confirm or change the predicted scene.
+    """
+    inside = mask > 0
+    if inside.mean() < 0.04:
+        return False
+    ys, xs = np.nonzero(inside)
+    tall = (np.ptp(ys) + 1) / (np.ptp(xs) + 1)
+    ycrcb = cv2.cvtColor(bgr, cv2.COLOR_BGR2YCrCb)
+    cr, cb = ycrcb[..., 1], ycrcb[..., 2]
+    skin = (cr >= 135) & (cr <= 175) & (cb >= 85) & (cb <= 130)
+    skin_share = float(skin[inside].mean())
+    return bool(tall >= 1.5 and 0.04 <= skin_share <= 0.6)
+
+
+# ─── prediction ───────────────────────────────────────────────────────────────
+
+
+def _signals(images: list[Path], settings: Settings) -> SceneSignals:
+    from reverse3d.vision.mask_extractor import foreground_mask, mask_score
+
+    n = len(images)
+    step = max(1, n // _SAMPLE)
+    sample = images[::step][:_SAMPLE]
+    cameras: list[str] = []
+    positions: list[tuple[float, float]] = []
+    pitches: list[float] = []
+    for path in images:
+        camera, position, pitch = _photo_metadata(path)
+        if camera:
+            cameras.append(camera)
+        if position:
+            positions.append(position)
+        if pitch is not None:
+            pitches.append(pitch)
+
+    isolation, people, rect, sky = [], 0, [], []
+    for path in sample:
+        small, _ = downscale(load_image(path, settings), _SIDE)
+        gray = cv2.cvtColor(small, cv2.COLOR_BGR2GRAY)
+        try:
+            mask = foreground_mask(small, work_side=320)
+            isolation.append(mask_score(mask))
+            people += _looks_like_person(small, mask)
+        except cv2.error:
+            isolation.append(0.0)
+        rect.append(_rectilinear(gray))
+        sky.append(_sky(small))
+
+    camera = max(set(cameras), key=cameras.count) if cameras else None
+    drone = bool(camera and camera.lower().startswith(_DRONE_MAKES)) or bool(pitches)
+    return SceneSignals(
+        photos=n,
+        sampled=len(sample),
+        gps_photos=len(positions),
+        gps_spread_m=_spread_m(positions),
+        drone=drone,
+        nadir_share=sum(1 for p in pitches if p <= -60) / len(pitches) if pitches else 0.0,
+        isolation=float(np.mean(isolation)) if isolation else 0.0,
+        people_share=people / len(sample) if sample else 0.0,
+        rectilinear=float(np.mean(rect)) if rect else 0.0,
+        sky_share=float(np.mean(sky)) if sky else 0.0,
+        camera=camera,
+    )
+
+
+def score_scene(signals: SceneSignals) -> tuple[dict[str, float], list[str]]:
+    """Scores per scene kind (higher wins) and the reasons that drove them."""
+    s = signals
+    wide = s.gps_spread_m is not None and s.gps_spread_m > 80
+    building_range = s.gps_spread_m is not None and 8 < s.gps_spread_m < 400
+    reasons: list[str] = []
+    if s.drone:
+        reasons.append("drone")
+    if wide:
+        reasons.append("gps_wide")
+    if s.nadir_share > 0.3:
+        reasons.append("nadir")
+    if s.people_share >= 0.4:
+        reasons.append("people")
+    if s.isolation >= 0.45:
+        reasons.append("isolated_object")
+    if s.rectilinear >= 0.25:
+        reasons.append("straight_lines")
+    if s.sky_share >= 0.25:
+        reasons.append("sky")
+    scores = {
+        "object": 0.15 + 0.7 * s.isolation + 0.15 * (1 - s.rectilinear) - 0.4 * s.people_share,
+        "character": 0.9 * s.people_share + 0.2 * s.isolation,
+        "architecture": 0.65 * s.rectilinear
+        + 0.25 * s.sky_share
+        + 0.15 * building_range
+        + 0.2 * (1 - s.isolation)
+        - 0.3 * s.nadir_share,
+        "landscape": 0.45 * s.drone
+        + 0.3 * wide
+        + 0.35 * s.nadir_share
+        + 0.25 * s.sky_share * (1 - s.rectilinear)
+        + 0.1 * (1 - s.isolation),
+    }
+    return {k: round(max(v, 0.0), 3) for k, v in scores.items()}, reasons
+
+
+def detect_scene(image_dir: str | Path, settings: Settings) -> SceneDetection:
+    """Predict the scene kind of a photo folder (takes a few seconds)."""
+    directory = validate_input_dir(image_dir)
+    images = list_images(
+        directory, max_images=settings.max_images, max_bytes=settings.max_input_bytes
+    )
+    signals = _signals(images, settings)
+    scores, reasons = score_scene(signals)
+    kind: SceneKind = max(SCENES, key=lambda k: scores[k])
+    ranked = sorted(scores.values(), reverse=True)
+    margin = ranked[0] - (ranked[1] if len(ranked) > 1 else 0.0)
+    confidence = round(min(0.97, 0.5 + margin * 1.5), 2)
+    preset = SCENE_PRESETS[kind]
+    enough = signals.photos >= preset.min_photos
+    if not enough:
+        reasons.append("few_photos")
+    advice = scene_advice(kind, signals.photos)
+    logger.info(
+        "Scene: %s (%.0f%%) from %d photo(s): %s", kind, confidence * 100, signals.photos, reasons
+    )
+    return SceneDetection(
+        kind=kind,
+        confidence=confidence,
+        reasons=reasons,
+        scores=scores,
+        signals=signals,
+        min_photos=preset.min_photos,
+        recommended=preset.recommended,
+        enough_photos=enough,
+        advice=advice,
+    )
+
+
+_ADVICE_ES: dict[str, str] = {
+    "object": (
+        "Objeto: 40-60 fotos (mínimo 20) en 4 perfiles: anillo bajo a 10-20° (16), medio a "
+        "35-45° (16), alto a 60-70° (12) y 4 desde arriba, sin mover el objeto, luz pareja y "
+        "sin reflejos."
+    ),
+    "character": (
+        "Personaje: 60-100 fotos (mínimo 40) en menos de 2 minutos, con la persona quieta en "
+        "pose A (brazos separados), mirando a un punto fijo. Anillos a la altura de las rodillas "
+        "(24), del pecho (24) y por encima de la cabeza (16), más 10-12 de cerca de la cara. "
+        "Ropa mate, sin pelo suelto al viento."
+    ),
+    "architecture": (
+        "Arquitectura: 80-200 fotos (mínimo 50). Rodea el edificio a distancia constante con "
+        "una foto cada 2-3 pasos (70 % de solape), a la altura de los ojos y otra vuelta más "
+        "alejada para ver el techo; fachadas de frente y esquinas a 45°. Interiores: desde las "
+        "esquinas en diagonal, una foto por metro. Día nublado, sin gente ni autos moviéndose."
+    ),
+    "landscape": (
+        "Paisaje (dron): 100-400 fotos (mínimo 60). Vuelo en cuadrícula a altura constante "
+        "(30-120 m) con 75-80 % de solape frontal y 65-70 % lateral, cámara vertical (90°), más "
+        "una pasada oblicua a 45-60° para taludes y fachadas. GPS activado, misma exposición, "
+        "sin sombras duras del mediodía."
+    ),
+}
+
+
+def scene_advice(kind: str, photos: int) -> list[str]:
+    """Capture advice (Spanish) for a scene kind, plus a note if photos are few."""
+    preset = SCENE_PRESETS[kind]
+    advice = [_ADVICE_ES[kind]]
+    if photos < preset.min_photos:
+        advice.insert(
+            0,
+            f"Solo hay {photos} fotos: para {SCENE_LABEL_ES[kind].lower()} se necesitan al "
+            f"menos {preset.min_photos} ({preset.recommended[0]}-{preset.recommended[1]} "
+            "recomendadas).",
+        )
+    return advice
+
+
+def has_gps(image_dir: Path, minimum: int = 3) -> bool:
+    """True when at least ``minimum`` photos carry GPS positions (spatial matching)."""
+    count = 0
+    for path in sorted(image_dir.iterdir()):
+        if path.is_file() and _photo_metadata(path)[1] is not None:
+            count += 1
+            if count >= minimum:
+                return True
+    return False

{reverse3d-0.5.0 → reverse3d-0.5.2}/reverse3d/vision/feature_matcher.py

@@ -308,10 +308,13 @@ def analyze_image_set(
     recommendations: list[str] = []
     if n < 3:
         recommendations.append(
-            "Capture at least 20-40 photos around the object for photogrammetry."
+            "Take at least 20 photos (40-60 recommended) around the object: three rings at "
+            "10-20, 35-45 and 60-70 degrees plus a few from above (see docs/captura.md)."
         )
     elif n < 15:
-        recommendations.append("Few images: add more viewpoints (aim for 60-80% overlap).")
+        recommendations.append(
+            "Few images: aim for 40-60 photos with 60-80% overlap between neighbours."
+        )
     blurry = [q.name for q in qualities if "blurry" in q.issues]
     if blurry:
         recommendations.append(

{reverse3d-0.5.0 → reverse3d-0.5.2/reverse3d.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reverse3d
-Version: 0.5.0
+Version: 0.5.2
 Summary: AI-agent-ready toolkit for 3D reverse engineering: image analysis, photogrammetry, mesh repair, primitive fitting and headless rendering.
 Author-email: Voxel Enterprise <info@voxel.lat>
 Maintainer-email: Voxel Enterprise <info@voxel.lat>
@@ -425,6 +425,10 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 
 **Formatos:** imágenes `png jpg jpeg tif tiff bmp webp`, y fotos de iPhone `heic heif` (se convierten a JPEG conservando el EXIF) · mallas `stl obj ply glb gltf off` · nubes `ply xyz pcd`.
 
+**Perfiles de escena:** reverse3d predice si las fotos son de un objeto, un personaje, arquitectura o un paisaje (`reverse3d scene detect <carpeta>`) y ajusta la reconstrucción; también puedes elegirlo con `reverse3d auto <carpeta> --scene architecture`.
+
+**¿Cómo tomar las fotos?** Mínimo 20, recomendadas 40-60, en 4 perfiles (anillos a 10-20°, 35-45° y 60-70°, y 4 desde arriba), sin mover el objeto, con luz pareja y sin reflejos. Guía completa: [docs/captura.md](docs/captura.md).
+
 ---
 
 ## Herramientas externas opcionales

{reverse3d-0.5.0 → reverse3d-0.5.2}/reverse3d.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ reverse3d/offline.py
 reverse3d/profiles.py
 reverse3d/py.typed
 reverse3d/recipes.py
+reverse3d/scenes.py
 reverse3d/security.py
 reverse3d/setup_agents.py
 reverse3d/userconfig.py
@@ -64,5 +65,6 @@ tests/test_offline_autopilot.py
 tests/test_optional_extras.py
 tests/test_reconstruction.py
 tests/test_render.py
+tests/test_scenes.py
 tests/test_security.py
 tests/test_vision.py

{reverse3d-0.5.0 → reverse3d-0.5.2}/tests/test_offline_autopilot.py

@@ -278,7 +278,14 @@ class TestAutoRun:
         assert summary["fallback"]["from"] == "photos_to_model"
         assert summary["warnings"][0].startswith("A full 3D model could not be reconstructed")
         assert [a["ok"] for a in summary["auto"]["attempts"]] == [False, True]
-        assert summary["next_steps"][0].startswith("Para un modelo 3D completo")
+        # Capture advice for the predicted scene comes first.
+        assert summary["auto"]["scene"]["kind"] in (
+            "object",
+            "character",
+            "architecture",
+            "landscape",
+        )
+        assert "fotos" in summary["next_steps"][0]
         assert (tmp_path / "o" / "RESUMEN.md").is_file()
 
     def test_capture_error_is_kept_when_the_fallback_fails(

reverse3d-0.5.2/tests/test_scenes.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+import pytest
+from PIL import Image
+
+from reverse3d.config import Settings
+from reverse3d.scenes import (
+    SCENE_PRESETS,
+    SceneSignals,
+    _photo_metadata,
+    _rectilinear,
+    _spread_m,
+    detect_scene,
+    has_gps,
+    scene_advice,
+    score_scene,
+)
+
+
+def _winner(**signals: object) -> str:
+    scores, _ = score_scene(SceneSignals(photos=50, sampled=8, **signals))  # type: ignore[arg-type]
+    return max(scores, key=scores.__getitem__)
+
+
+@pytest.mark.parametrize(
+    ("signals", "kind"),
+    [
+        ({"isolation": 0.7, "rectilinear": 0.05}, "object"),
+        ({"isolation": 0.55, "people_share": 0.8}, "character"),
+        (
+            {"isolation": 0.1, "rectilinear": 0.6, "sky_share": 0.4, "gps_spread_m": 60.0},
+            "architecture",
+        ),
+        (
+            {"drone": True, "nadir_share": 0.9, "gps_spread_m": 400.0, "isolation": 0.05},
+            "landscape",
+        ),
+    ],
+)
+def test_each_scene_wins_with_its_signals(signals: dict[str, object], kind: str) -> None:
+    assert _winner(**signals) == kind
+
+
+def test_reasons_explain_the_prediction() -> None:
+    _, reasons = score_scene(
+        SceneSignals(photos=200, sampled=8, drone=True, nadir_share=0.9, gps_spread_m=300.0)
+    )
+    assert {"drone", "nadir", "gps_wide"} <= set(reasons)
+
+
+def _facade() -> np.ndarray:
+    image = np.full((480, 640), 120, np.uint8)
+    for x in range(40, 640, 80):
+        cv2.line(image, (x, 60), (x, 470), 255, 3)
+    for y in range(60, 480, 60):
+        cv2.line(image, (40, y), (600, y), 30, 3)
+    return image
+
+
+def test_straight_lines_are_measured() -> None:
+    noise = np.random.default_rng(0).integers(0, 255, (480, 640), dtype=np.uint8)
+    assert _rectilinear(_facade()) > 0.25 > _rectilinear(cv2.GaussianBlur(noise, (9, 9), 0))
+
+
+def _dms(value: float) -> tuple[float, float, float]:
+    d = int(value)
+    m = int((value - d) * 60)
+    return (float(d), float(m), round(((value - d) * 60 - m) * 60, 4))
+
+
+def _gps_jpeg(path: Path, lat: float, lon: float, make: str = "DJI", model: str = "FC3582") -> Path:
+    image = Image.fromarray(np.random.default_rng(1).integers(0, 255, (64, 64, 3), np.uint8))
+    exif = Image.Exif()
+    exif[271], exif[272] = make, model
+    gps = exif.get_ifd(0x8825)
+    gps[1], gps[2] = ("N" if lat >= 0 else "S"), _dms(abs(lat))
+    gps[3], gps[4] = ("E" if lon >= 0 else "W"), _dms(abs(lon))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    image.save(path, "JPEG", exif=exif)
+    return path
+
+
+def test_exif_gps_and_drone_camera(tmp_path: Path) -> None:
+    a = _gps_jpeg(tmp_path / "a.jpg", 8.98, -79.52)
+    camera, position, _ = _photo_metadata(a)
+    assert camera == "DJI FC3582"
+    assert position is not None and position[0] == pytest.approx(8.98, abs=1e-4)
+    assert position[1] == pytest.approx(-79.52, abs=1e-4)
+    for i in range(1, 3):
+        _gps_jpeg(tmp_path / f"{i}.jpg", 8.98 + i * 0.001, -79.52)
+    assert has_gps(tmp_path)
+    assert _spread_m([(8.98, -79.52), (8.981, -79.52)]) == pytest.approx(111.2, rel=0.02)
+
+
+def test_detect_scene_on_a_drone_set(tmp_path: Path, settings: Settings) -> None:
+    for i in range(6):
+        _gps_jpeg(tmp_path / "vuelo" / f"DJI_{i:04d}.jpg", 8.98 + i * 0.0005, -79.52 + i * 0.0005)
+    detection = detect_scene(tmp_path / "vuelo", settings)
+    assert detection.kind == "landscape"
+    assert "drone" in detection.reasons
+    assert not detection.enough_photos and "few_photos" in detection.reasons
+    assert detection.advice[0].startswith("Solo hay 6 fotos")
+
+
+def test_presets_and_advice_cover_every_scene() -> None:
+    for kind, preset in SCENE_PRESETS.items():
+        assert preset.min_photos <= preset.recommended[0] < preset.recommended[1]
+        assert scene_advice(kind, preset.recommended[0])[0]
+    assert not SCENE_PRESETS["architecture"].fill_holes
+    assert SCENE_PRESETS["object"].fill_holes

{reverse3d-0.5.0 → reverse3d-0.5.2}/tests/test_vision.py

@@ -119,7 +119,7 @@ class TestFeatureMatching:
         assert report.image_count == 2
         assert len(report.pairs) == 1
         assert report.suitable_for_photogrammetry is False  # only 2 images
-        assert any("20-40" in r for r in report.recommendations)
+        assert any("at least 20 photos" in r for r in report.recommendations)
 
 
 def test_largest_group_ignores_capture_order() -> None:

reverse3d-0.5.0/reverse3d/_version.py

@@ -1 +0,0 @@
-__version__ = "0.5.0"