reverse3d 0.4.0__py3-none-any.whl

reverse3d/__init__.py

@@ -0,0 +1,39 @@
+"""reverse3d — AI-agent-ready toolkit for 3D reverse engineering.
+
+Developed and maintained by Voxel Enterprise (https://voxel.lat).
+
+Subpackages are imported lazily by the caller so that ``import reverse3d`` stays
+cheap and never pulls optional heavy stacks (Open3D, PyTorch, PyVista).
+"""
+
+from reverse3d._about import AUTHOR as _AUTHOR
+from reverse3d._about import COPYRIGHT as _COPYRIGHT
+from reverse3d._about import LICENSE as _LICENSE
+from reverse3d._version import __version__
+from reverse3d.config import Settings
+from reverse3d.errors import (
+    DependencyMissingError,
+    ExternalToolError,
+    InputValidationError,
+    ProcessingError,
+    Reverse3DError,
+    SecurityViolationError,
+)
+
+__author__ = _AUTHOR
+__copyright__ = _COPYRIGHT
+__license__ = _LICENSE
+
+__all__ = [
+    "DependencyMissingError",
+    "ExternalToolError",
+    "InputValidationError",
+    "ProcessingError",
+    "Reverse3DError",
+    "SecurityViolationError",
+    "Settings",
+    "__author__",
+    "__copyright__",
+    "__license__",
+    "__version__",
+]

reverse3d/__main__.py

@@ -0,0 +1,4 @@
+from reverse3d.cli import main
+
+if __name__ == "__main__":
+    main()

reverse3d/_about.py

@@ -0,0 +1,15 @@
+"""Authorship and provenance of reverse3d. Single source of truth.
+
+These values are protected: ``scripts/check_authorship.py`` (CI + pre-commit)
+fails if they change, and ``.github/CODEOWNERS`` requires the owner's approval.
+Forks must keep this attribution (Apache-2.0 §4) and may not present
+themselves as the official project (see TRADEMARKS.md).
+"""
+
+AUTHOR = "Voxel Enterprise"
+AUTHOR_EMAIL = "info@voxel.lat"
+AUTHOR_URL = "https://voxel.lat"
+COPYRIGHT = "Copyright 2026 Voxel Enterprise"
+LICENSE = "Apache-2.0"
+OFFICIAL_REPOSITORY = "https://github.com/rellytechgame/Reverse3D-tool"
+OFFICIAL_DOCS = OFFICIAL_REPOSITORY + "/blob/main/docs/authenticity.md"

reverse3d/_version.py

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

reverse3d/agent/__init__.py

@@ -0,0 +1,5 @@
+"""Agent integration: tool schemas, sandboxed dispatcher and MCP server."""
+
+from reverse3d.agent.tools import TOOLS, execute_tool, tool_definitions
+
+__all__ = ["TOOLS", "execute_tool", "tool_definitions"]

reverse3d/agent/compact.py

@@ -0,0 +1,110 @@
+"""Token-efficient shaping of tool results for LLMs (``verbosity=compact``).
+
+* Absolute paths inside the workspace become short relative paths.
+* Floats are rounded to 6 significant digits.
+* ``None`` values and empty containers are dropped.
+* Long lists of objects are truncated with an ``{"_omitted": n}`` marker.
+* Per-tool reducers keep only what an agent needs to decide the next step
+  (e.g. only the images *with problems* from an image-set analysis).
+
+Nothing is lost: recipes write the full report to disk, and
+``REVERSE3D_VERBOSITY=full`` disables compaction.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path, PurePath
+from typing import Any
+
+_MAX_LIST = 12
+
+
+def _relativize(value: str, root: str) -> str:
+    if len(value) < 3 or not PurePath(value).is_absolute():
+        return value
+    try:
+        rel = Path(value).relative_to(root)
+    except ValueError:
+        return value
+    return rel.as_posix() or "."
+
+
+def shrink(value: Any, root: str, *, max_list: int = _MAX_LIST) -> Any:
+    """Recursively compact a JSON-like structure."""
+    if isinstance(value, bool) or value is None or isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return float(f"{value:.6g}")
+    if isinstance(value, str):
+        return _relativize(value, root)
+    if isinstance(value, dict):
+        out = {}
+        for key, item in value.items():
+            item = shrink(item, root, max_list=max_list)
+            if item is None or item == [] or item == {}:
+                continue
+            out[key] = item
+        return out
+    if isinstance(value, (list, tuple)):
+        items = [shrink(v, root, max_list=max_list) for v in value]
+        if len(items) > max_list and any(isinstance(v, dict) for v in items):
+            return [*items[:max_list], {"_omitted": len(items) - max_list}]
+        return items
+    return value
+
+
+def _reduce_analysis(result: dict[str, Any]) -> dict[str, Any]:
+    images = result.get("images", [])
+    pairs = result.get("pairs", [])
+    return {
+        "image_count": result.get("image_count"),
+        "suitable_for_photogrammetry": result.get("suitable_for_photogrammetry"),
+        "recommendations": result.get("recommendations"),
+        "images_with_issues": [
+            {"name": i["name"], "issues": i["issues"]} for i in images if i.get("issues")
+        ],
+        "weak_links": result.get("weak_links"),
+        "median_pair_inliers": sorted(p["inliers"] for p in pairs)[len(pairs) // 2]
+        if pairs
+        else None,
+    }
+
+
+def _reduce_clean(result: dict[str, Any]) -> dict[str, Any]:
+    keys = ("faces", "watertight", "components", "boundary_edges", "obb_extents", "volume")
+    return {
+        "output_path": result.get("output_path"),
+        "before": {k: result["before"].get(k) for k in keys},
+        "after": {k: result["after"].get(k) for k in keys},
+        "steps": result.get("steps"),
+        "warnings": result.get("warnings"),
+    }
+
+
+def _reduce_photogrammetry(result: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in result.items() if k not in ("stages", "sparse_model_dir")}
+
+
+def _reduce_fit(result: dict[str, Any]) -> dict[str, Any]:
+    prims = [
+        {"kind": p["kind"], "inlier_ratio": p["inlier_ratio"], **p["params"]}
+        for p in result.get("primitives", [])
+    ]
+    return {**{k: v for k, v in result.items() if k != "primitives"}, "primitives": prims}
+
+
+REDUCERS: dict[str, Callable[[dict[str, Any]], dict[str, Any]]] = {
+    "reverse3d_analyze_images": _reduce_analysis,
+    "reverse3d_clean_mesh": _reduce_clean,
+    "reverse3d_photogrammetry": _reduce_photogrammetry,
+    "reverse3d_fit_primitives": _reduce_fit,
+}
+
+
+def compact_result(tool: str, result: Any, workspace: Path) -> Any:
+    """Apply the tool's reducer (if any) and :func:`shrink`."""
+    reducer = REDUCERS.get(tool)
+    if reducer is not None and isinstance(result, dict):
+        result = reducer(result)
+    return shrink(result, str(workspace))

reverse3d/agent/mcp_server.py

@@ -0,0 +1,171 @@
+"""Model Context Protocol (MCP) server over stdio (``[mcp]`` extra).
+
+Exposes the reverse3d tools and slash-command prompts to any MCP client
+(Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Codex,
+OpenCode...).
+
+* Transport is **stdio only**: no network port is opened, so the server is only
+  reachable by the local client process that spawned it.
+* Settings are re-read on every call, so ``reverse3d_configure`` (e.g. switching
+  to GPU) takes effect immediately without restarting the client.
+* Tool calls run in a worker thread and are serialised by a semaphore: heavy
+  jobs (photogrammetry, rendering) cannot be launched concurrently by a
+  runaway agent (OWASP LLM10).
+* All logging goes to stderr; stdout carries only MCP frames.
+* Works with both MCP Python SDK generations: 1.x registers handlers with
+  decorators, 2.x passes them to the ``Server`` constructor.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from reverse3d._version import __version__
+from reverse3d.agent.prompts import PROMPTS, SERVER_INSTRUCTIONS, render_prompt
+from reverse3d.agent.tools import execute_tool, input_schema, visible_tools
+from reverse3d.config import Settings
+from reverse3d.errors import DependencyMissingError
+
+logger = logging.getLogger(__name__)
+
+SettingsProvider = Callable[[], Settings]
+
+
+def build_server(settings_provider: SettingsProvider, *, max_concurrent: int = 1) -> Any:
+    """Create the MCP ``Server`` with tool and prompt handlers registered.
+
+    Args:
+        settings_provider: returns fresh settings for each request.
+
+    Raises:
+        DependencyMissingError: the ``mcp`` package is not installed.
+    """
+    try:
+        import anyio
+        import mcp.types as types
+        from mcp.server.lowlevel import Server
+    except ImportError as exc:
+        raise DependencyMissingError(
+            "The MCP server requires the 'mcp' package.", hint='pip install "reverse3d[mcp]"'
+        ) from exc
+
+    limiter = anyio.Semaphore(max(1, max_concurrent))
+    toolset = settings_provider().toolset  # the tool list is fixed per server session
+
+    # camelCase keys are field names in SDK 1.x and aliases in 2.x: model_validate
+    # accepts the same payload on both generations.
+    def tool_list() -> list[Any]:
+        return [
+            types.Tool.model_validate(
+                {"name": s.name, "description": s.description, "inputSchema": input_schema(s)}
+            )
+            for s in visible_tools(toolset)
+        ]
+
+    def prompt_list() -> list[Any]:
+        return [
+            types.Prompt.model_validate(
+                {
+                    "name": p.name,
+                    "description": p.description,
+                    "arguments": [
+                        {"name": a.name, "description": a.description, "required": a.required}
+                        for a in p.arguments
+                    ],
+                }
+            )
+            for p in PROMPTS.values()
+        ]
+
+    def prompt_result(name: str, arguments: dict[str, str] | None) -> Any:
+        try:
+            text = render_prompt(name, arguments)
+        except KeyError:
+            text = f"Unknown prompt '{name}'. Available: {', '.join(PROMPTS)}"
+        except ValueError as exc:
+            text = str(exc)
+        return types.GetPromptResult.model_validate(
+            {
+                "description": PROMPTS[name].description if name in PROMPTS else None,
+                "messages": [{"role": "user", "content": {"type": "text", "text": text}}],
+            }
+        )
+
+    async def run_tool(name: str, arguments: dict[str, Any] | None) -> tuple[Any, bool]:
+        async with limiter:
+            result = await anyio.to_thread.run_sync(
+                execute_tool, name, arguments, settings_provider()
+            )
+        text = types.TextContent(type="text", text=json.dumps(result, ensure_ascii=False))
+        return text, not result.get("ok", False)
+
+    if hasattr(Server, "list_tools"):  # MCP SDK 1.x: decorator registration
+        try:
+            server: Any = Server("reverse3d", instructions=SERVER_INSTRUCTIONS)
+        except TypeError:  # very old 1.x without instructions support
+            server = Server("reverse3d")
+
+        @server.list_tools()
+        async def list_tools() -> list[Any]:
+            return tool_list()
+
+        @server.call_tool()
+        async def call_tool(name: str, arguments: dict[str, Any] | None) -> list[Any]:
+            content, _ = await run_tool(name, arguments)
+            return [content]
+
+        @server.list_prompts()
+        async def list_prompts() -> list[Any]:
+            return prompt_list()
+
+        @server.get_prompt()
+        async def get_prompt(name: str, arguments: dict[str, str] | None) -> Any:
+            return prompt_result(name, arguments)
+
+        return server
+
+    # MCP SDK 2.x: constructor registration with (ctx, params) handlers.
+    async def on_list_tools(ctx: Any, params: Any) -> Any:
+        return types.ListToolsResult.model_validate({"tools": tool_list()})
+
+    async def on_call_tool(ctx: Any, params: Any) -> Any:
+        content, is_error = await run_tool(params.name, params.arguments)
+        return types.CallToolResult.model_validate({"content": [content], "isError": is_error})
+
+    async def on_list_prompts(ctx: Any, params: Any) -> Any:
+        return types.ListPromptsResult.model_validate({"prompts": prompt_list()})
+
+    async def on_get_prompt(ctx: Any, params: Any) -> Any:
+        return prompt_result(params.name, params.arguments)
+
+    from reverse3d._about import AUTHOR, AUTHOR_URL
+
+    return Server(
+        "reverse3d",
+        version=__version__,
+        title="reverse3d",
+        description=f"3D modeling and reverse engineering toolkit by {AUTHOR}",
+        website_url=AUTHOR_URL,
+        instructions=SERVER_INSTRUCTIONS,
+        on_list_tools=on_list_tools,
+        on_call_tool=on_call_tool,
+        on_list_prompts=on_list_prompts,
+        on_get_prompt=on_get_prompt,
+    )
+
+
+def serve(settings_provider: SettingsProvider, *, max_concurrent: int = 1) -> None:
+    """Run the MCP stdio server until the client disconnects."""
+    server = build_server(settings_provider, max_concurrent=max_concurrent)
+    import anyio
+    from mcp.server.stdio import stdio_server
+
+    async def _main() -> None:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(read_stream, write_stream, server.create_initialization_options())
+
+    logger.info("reverse3d MCP server starting (workspace=%s)", settings_provider().workspace.name)
+    anyio.run(_main)

reverse3d/agent/prompts.py

@@ -0,0 +1,173 @@
+"""MCP prompts: ready-made commands that clients show as slash commands.
+
+Example in Claude Code: ``/mcp__reverse3d__fotos-a-3d capturas/taza``. Each
+prompt expands into a short instruction that makes the agent call the right
+tool in one step, so users don't need to know tool names or arguments.
+
+Prompt arguments come from the user and are only interpolated into text sent
+to the model (never executed); they are length-capped.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+_ARG_MAX = 300
+
+#: Short guidance sent to MCP clients that support server instructions.
+SERVER_INSTRUCTIONS = (
+    "reverse3d: local 3D reverse-engineering tools. Prefer reverse3d_run_recipe (one call per "
+    "workflow; recipe=auto when unsure of the input type). Works offline. Paths are relative "
+    "to the workspace. Use reverse3d_configure to switch "
+    "device (cpu/gpu) or profile (fast/balanced/quality). If a result has ok=false, read "
+    "error.hint and retry. Report sizes with units and show the render path to the user."
+)
+
+
+@dataclass(frozen=True)
+class PromptArg:
+    name: str
+    description: str
+    required: bool = True
+
+
+@dataclass(frozen=True)
+class PromptSpec:
+    name: str
+    description: str
+    template: str
+    arguments: tuple[PromptArg, ...] = field(default_factory=tuple)
+
+
+PROMPTS: dict[str, PromptSpec] = {
+    p.name: p
+    for p in (
+        PromptSpec(
+            "procesar",
+            "Lo que sea (fotos, plano, foto o malla) → detecta qué es y lo procesa solo.",
+            "Run reverse3d_run_recipe with recipe=auto, input_path='{entrada}', "
+            "output_dir='{salida}'. Tell the user what was detected, the dimensions, the "
+            "result files and the next_steps from the summary. If it failed, explain the hint.",
+            (
+                PromptArg("entrada", "Carpeta de fotos, imagen o archivo 3D dentro del workspace"),
+                PromptArg("salida", "Carpeta de resultados", required=False),
+            ),
+        ),
+        PromptSpec(
+            "fotos-a-3d",
+            "Fotos de un objeto → modelo 3D medido y renderizado (fotogrametría).",
+            "Run reverse3d_run_recipe with recipe=photos_to_model, input_path='{carpeta}', "
+            "output_dir='{salida}'. If the photo check fails, explain the recommendations to the "
+            "user before retrying. Then report the dimensions and the render path.",
+            (
+                PromptArg("carpeta", "Carpeta con las fotos, dentro del workspace"),
+                PromptArg("salida", "Carpeta de resultados", required=False),
+            ),
+        ),
+        PromptSpec(
+            "plano-a-pieza",
+            "Plano, careta o silueta → pieza 3D extruida con escala real.",
+            "Run reverse3d_run_recipe with recipe=plan_to_part, input_path='{imagen}', "
+            "output_dir='{salida}', thickness={espesor}{escala}. Report the dimensions and the "
+            "render path.",
+            (
+                PromptArg("imagen", "Imagen del plano o careta"),
+                PromptArg("espesor", "Espesor de extrusión (p. ej. 5)", required=False),
+                PromptArg("mm_por_pixel", "Escala, milímetros por píxel", required=False),
+                PromptArg("salida", "Carpeta de resultados", required=False),
+            ),
+        ),
+        PromptSpec(
+            "escaneo-a-cad",
+            "Malla o escaneo → limpieza, cotas, primitivas y código CAD (OpenSCAD/CadQuery).",
+            "Run reverse3d_run_recipe with recipe=scan_to_cad, input_path='{malla}', "
+            "output_dir='{salida}'. Summarise the dimensions, the detected primitives "
+            "(radii, planes) and the generated CAD files.",
+            (
+                PromptArg("malla", "Archivo STL/OBJ/PLY/GLB"),
+                PromptArg("salida", "Carpeta de resultados", required=False),
+            ),
+        ),
+        PromptSpec(
+            "foto-a-relieve",
+            "Una sola foto → relieve 2.5D aproximado (IA de profundidad).",
+            "Run reverse3d_run_recipe with recipe=photo_to_relief, input_path='{imagen}', "
+            "output_dir='{salida}'. Remind the user that the depth is relative, not metric.",
+            (
+                PromptArg("imagen", "Foto de entrada"),
+                PromptArg("salida", "Carpeta de resultados", required=False),
+            ),
+        ),
+        PromptSpec(
+            "medir",
+            "Cotas, volumen y render de una malla existente.",
+            "Run reverse3d_run_recipe with recipe=mesh_report, input_path='{malla}', "
+            "output_dir='{salida}'. Report the dimensions in a small table.",
+            (
+                PromptArg("malla", "Archivo de malla"),
+                PromptArg("salida", "Carpeta de resultados", required=False),
+            ),
+        ),
+        PromptSpec(
+            "usar-gpu",
+            "Usar la GPU (CUDA/Apple) en todas las operaciones.",
+            "Call reverse3d_configure with device='gpu'. Then tell the user which GPU was "
+            "detected, or that it will fall back to CPU if none is usable.",
+        ),
+        PromptSpec(
+            "usar-cpu",
+            "Forzar CPU en todas las operaciones.",
+            "Call reverse3d_configure with device='cpu' and confirm the new setting.",
+        ),
+        PromptSpec(
+            "rendimiento",
+            "Elegir perfil: fast (rápido), balanced (equilibrado) o quality (máxima calidad).",
+            "Call reverse3d_configure with profile='{perfil}' and confirm the new setting.",
+            (PromptArg("perfil", "fast | balanced | quality"),),
+        ),
+        PromptSpec(
+            "estado",
+            "Ver capacidades instaladas, GPU detectada y configuración actual.",
+            "Call reverse3d_environment_check and reverse3d_configure (no arguments). Summarise "
+            "in 5 lines what is available and what is missing, with how to install it.",
+        ),
+    )
+}
+
+
+def _clip(value: str) -> str:
+    return value.replace("'", "").replace("\n", " ").strip()[:_ARG_MAX]
+
+
+def render_prompt(name: str, arguments: dict[str, str] | None) -> str:
+    """Expand a prompt template with user arguments and sensible defaults.
+
+    Raises:
+        KeyError: unknown prompt.
+        ValueError: missing required argument.
+    """
+    spec = PROMPTS[name]
+    args = {k: _clip(str(v)) for k, v in (arguments or {}).items() if v not in (None, "")}
+    for arg in spec.arguments:
+        if arg.required and arg.name not in args:
+            raise ValueError(f"Missing argument: {arg.name}")
+    source = (
+        args.get("entrada")
+        or args.get("carpeta")
+        or args.get("imagen")
+        or args.get("malla")
+        or "input"
+    )
+    stem = source.rstrip("/\\").replace("\\", "/").split("/")[-1].rsplit(".", 1)[0] or "result"
+    values = {
+        "salida": args.get("salida", f"out/{stem}"),
+        "espesor": args.get("espesor", "5"),
+        "escala": f", units_per_pixel={args['mm_por_pixel']}" if "mm_por_pixel" in args else "",
+        **args,
+    }
+    return spec.template.format_map(_Defaults(values))
+
+
+class _Defaults(dict[str, str]):
+    def __missing__(self, key: str) -> str:
+        return ""

reverse3d/agent/skill/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: reverse3d
+description: 3D modeling and reverse engineering with the local reverse3d toolkit. Use when the user wants to turn photos, a plan/stencil/silhouette, or an existing mesh (STL/OBJ/PLY/GLB) into a 3D model, measure dimensions, repair a mesh, get CAD code (OpenSCAD/CadQuery), render a preview, or switch reverse3d between CPU and GPU.
+---
+
+# reverse3d
+
+Local toolkit by Voxel Enterprise. Exposed as MCP tools named `reverse3d_*`. If those tools are not available, use the CLI: `reverse3d --json agent call <tool> --args '<json>'`. It has the same sandbox and the same output.
+
+## Golden rules (save tokens)
+
+1. **Use `reverse3d_run_recipe` first.** One call runs a whole workflow and returns a short summary. Full details go to `<output_dir>/report.json`; read that file only if the user asks for details.
+2. Paths are **relative to the workspace** (`REVERSE3D_WORKSPACE`). If the user attached a file, save it inside the workspace first.
+3. On `ok:false`, read `error.hint`, fix the arguments and retry once. Do not loop.
+4. Report sizes with units and give the user the `render` path. Say clearly when values are estimates.
+
+## Recipes
+
+| User wants | recipe | input_path |
+|---|---|---|
+| **Not sure what the input is / "process this"** | `auto` (detects it and retries smartly) | anything |
+| Photos of an object → 3D model | `photos_to_model` | folder of photos |
+| Plan, stencil or silhouette → part | `plan_to_part` (+ `thickness`, `units_per_pixel`) | image |
+| Scan or mesh → clean + dimensions + CAD | `scan_to_cad` | mesh |
+| A single photo → approximate relief | `photo_to_relief` | image |
+| Dimensions + preview of a mesh | `mesh_report` | mesh |
+
+Example: `reverse3d_run_recipe {"recipe":"plan_to_part","input_path":"in/bracket.png","output_dir":"out/bracket","thickness":3,"units_per_pixel":0.5}`.
+
+Scale tips: if the user knows one real dimension (e.g. "the plate is 100 mm wide and spans 200 px"), then `units_per_pixel = 100/200`. To convert meters to millimeters, use `scale: 1000`.
+
+`auto` returns `auto.detected` (what it found), `next_steps` (plain-language advice) and writes `RESUMEN.md` next to the results: relay those to the user.
+
+## Offline
+
+reverse3d works without internet. It switches to offline mode by itself when there is no connection. The only thing that needs a download is the AI depth model, and the installer fetches it. If a result says the model is missing, tell the user to run `reverse3d offline prepare` once while online. `reverse3d offline status` shows what works offline.
+
+## Autopilot without an agent
+
+`reverse3d watch` watches `<workspace>/bandeja`: anything dropped there is processed automatically into `<workspace>/resultados/<name>/`. Suggest it to users who want to work hands-free.
+
+## Device and performance
+
+- "use the GPU" → `reverse3d_configure {"device":"gpu"}`. It falls back to CPU if no usable GPU.
+- "use CPU" → `{"device":"cpu"}`. Faster / better quality → `{"profile":"fast"}` or `{"profile":"quality"}`.
+- Call `reverse3d_configure {}` to show the current settings and the detected GPU.
+- Call `reverse3d_environment_check` when something is missing (COLMAP, Blender, extras). It reports how to install it.
+
+## Individual tools (only for custom steps)
+
+`analyze_images`, `match_images`, `extract_mask`, `silhouette_to_mesh`, `photogrammetry`, `estimate_depth`, `mesh_from_point_cloud`, `clean_mesh`, `measure_mesh`, `fit_primitives`, `render`. All of them are prefixed with `reverse3d_`.
+
+Never overwrite user files unless the user asks. Pass `overwrite:true` only then.