Transformation Portal

Transformation Portal is a governed image and video processing platform for luxury real estate rendering, architectural visualization, and editorial finishing.

It combines orchestrated depth estimation, PBR map generation, material-aware finishing, optional AI enhancement, and portal/orchestrator surfaces behind explicit contracts, provenance, and reproducibility artifacts.

📊 Performance Dashboard | 📈 Latest Metrics

---

Repository Status

main tracks the active development branch for the repository.

For reproducible installs, pin a specific release tag from GitHub Releases instead of relying on branch prose. The release badge above reflects the latest tagged GitHub release.

Core entry points:

• lux-depth-v3 for orchestrated depth, PBR, materials, and enhancement workflows
• Portal/orchestrator HTTP surfaces with liveness (/ready, /healthz) plus operator-truth readiness at /v1/readiness
• Determinism, manifest, run-card, and provenance layers for governed execution

Quick discovery:

lux-depth-v3 --help

# If console scripts aren't on PATH, run as module:
python -m transformation_portal.lux_depth_v3 --help

# Portal/orchestrator contract gate:
make test-orchestrator-contract

Install a pinned release:

pip install "git+https://github.com/RC219805/Transformation_Portal.git@<release-tag>"

Replace <release-tag> with a tag from GitHub Releases.

Key docs:

• Portal + Orchestrator Quickstart
• Portal Secure Front Door Quickstart
• Portal Orchestrator Roadmap (Re-Baselined)
• Portal Frontdoor Roadmap
• DNA UX/UI Strategy Re-baseline
• Lux Depth V3 CLI Guide
• Context-Aware Rendering Guide

Portal surfaces:

• FastAPI on 127.0.0.1:8000 remains the system-of-record origin for the direct-debug portal HTML, /ready, and /v1/*.
• The secure front door in web/secure-landing/ is the managed browser entry point and keeps the backend API key out of browser code.
• The managed front door now splits the browser experience into three surfaces:
  • / public Dynamic Neural Access homepage
  • /login operator login
  • /portal governed operator console
• GET /healthz is the managed front-door liveness contract, GET /ready is backend liveness, and GET /v1/readiness is the execution-readiness matrix for the four governed pipelines.
• Shared public branding assets now live at web/secure-landing/public/brand/dna-symbol-*.svg, web/secure-landing/public/brand/dna-lockup-*.svg, and web/secure-landing/public/video/dna-loop.mp4.
• Direct FastAPI portal access is now a direct_debug workflow for local troubleshooting, not the preferred production browser path.
• The front door is a Node app. web/secure-landing now documents and enforces Node 22.x only for install, dev, test, build, and start flows.

---

Flagship Capability: Context-Aware Rendering

Context-Aware Rendering extracts architectural intelligence from construction documents (floor plans, elevations, specifications) and uses that context to inform processing decisions.

• Architectural context extraction from PDFs (room types, dimensions, materials, design style)
• Room-specific strategy derivation (kitchen, bedroom, bath, living, outdoor)
• Dimension-aware depth decisions (proportion-respecting depth logic)
• Style-consistent color decisions aligned to design language
• Document provenance: explicit linkage from construction docs → final render decisions

Docs:

• Context-Aware Rendering Guide

---

What this repository provides

Core capabilities:

• Context-aware rendering workflows (document-informed processing)
• Depth-aware enhancement (monocular depth + depth-guided processing)
• PBR Map Generation (Physically Based Rendering maps: normal, roughness, AO)
• AI-powered refinement (optional ML stack)
• Material Response technology (surface-aware finishing)
• Professional grading looks (LUT library for film/location/material aesthetics)
• TIFF workflows (high bit-depth + metadata preservation, where supported)
• Video grading workflows (FFmpeg-based pipelines)

---

Depth Models: Production and Research Tiers

Transformation Portal supports depth models across two tiers with different licensing and use cases.

Production Path

• DA3 (da3 backend): Primary production backend for Lux Depth V3
• Use for: The governed depth workflow surface. Select model_key="da3-metric" for the Apache-2.0 DA3 path, or model_key="da3" / model_key="da3-research" for the research-default selector.
• Requirement: Install a trusted ML core profile for actual DA3 inference. These trusted ML install flows are currently supported on macOS and Linux only; Windows users should use WSL2 or another Unix-like environment. For example: make install-ml-core or ./scripts/bootstrap/install_ml_stack.sh --profile core-cpu. CUDA-accelerated profiles are Linux-only.
• Default: Standard CLI flows resolve here unless a research-only backend is explicitly requested

Research & Non-Commercial

• DA3 research selector: model_key="da3" or model_key="da3-research"
• Depth Pro backend: depth_pro
• Use for: Explicitly acknowledged research and non-commercial evaluation paths
• Requirements: non_commercial_ok=True, plus Apple license acceptance for depth_pro

Important: The research-default DA3 selector is not part of the Apache-2.0 path. See ADR-0015: DA3 1.1 Non-Commercial Research Tier for governance details.

Research Preset Example

from transformation_portal.lux_depth_v3 import EnhanceConfig

# Non-commercial research (requires explicit opt-in)
config = EnhanceConfig(
    preset_requested="depth-anything-v3.1-research-m4",
    non_commercial_ok=True,  # Acknowledge CC BY-NC 4.0 restrictions
    depth_device="mps",      # Apple Silicon
)

---

Backend Selection

Lux Depth V3 supports multiple depth estimation backends with automatic fallback for robustness.

Primary User-Facing Backends

Backend	Model	License	Focal Length	Metric Depth	Checkpoint Required
da3 (default)	Depth Anything V3	Commercial-safe production path	❌	❌	No (auto-download)
depth_pro	Apple Depth Pro	Research-only with explicit license acceptance	✅	✅	Yes (1.9 GB)

The orchestrator also contains an internal synthetic fallback path used for explicit test/CI or fallback scenarios. It is not the primary production backend surfaced for normal CLI use.

Usage

Default (DA3):

lux-depth-v3 --input-dir ./input --output-dir ./output

If ./.venv-da3/bin/python exists, Lux Depth V3 auto-discovers that repo-local DA3 runtime before falling back to the main repo environment.

Recommended (DA3 via isolated Depth Anything 3 environment):

./scripts/setup/install_da3_runtime.sh

lux-depth-v3 --input-dir ./input --output-dir ./output

The repo-local DA3 setup script pins the upstream checkout to a validated ref under .runtime/Depth-Anything-3, keeps the interpreter contract at ./.venv-da3/bin/python, captures a .runtime/da3-pip-freeze.txt snapshot for debugging/provenance, and leaves the main repo .venv unchanged. Use --da3-python only when you want to override that repo-local runtime. Explicit --depth-backend da3 requests are now strict: if DA3 cannot be initialized, the command raises an actionable error instead of silently downgrading to DA2.

Depth Pro (requires license acceptance):

lux-depth-v3 \
  --input-dir ./input \
  --output-dir ./output \
  --depth-backend depth_pro \
  --depth-pro-python ./.venv-depth-pro/bin/python \
  --accept-apple-depth-pro-research-license true \
  --non-commercial-ok true

Python API:

from transformation_portal.lux_depth_v3 import EnhanceConfig
from transformation_portal.lux_depth_v3.orchestrator import EnhanceOrchestrator
from pathlib import Path

# Using Depth Pro
config = EnhanceConfig(
    depth_backend="depth_pro",
    depth_pro_checkpoint_path="checkpoints/depth_pro.pt",
    depth_pro_python_executable=".venv-depth-pro/bin/python",
    accept_apple_depth_pro_research_license=True,
    non_commercial_ok=True,
    depth_device="cpu",
    enable_v2=False,
)

orchestrator = EnhanceOrchestrator(config, Path("./output"))

DA3 live model tests remain opt-in: set TP_RUN_HF_MODEL_TESTS=1 before running the real Hugging Face DA3 integration tests.

Fallback Behavior

If the requested backend is unavailable, the orchestrator records the resolution outcome in backend metadata and falls back through the configured operational chain. In explicit test or constrained environments, a synthetic fallback path can also be enabled.

Backend Metadata

All processing manifests include backend selection metadata:

• requested_backend: User's requested backend
• resolved_backend: Actually used backend
• resolution_status: "success" or "fallback"
• resolution_reason: Explanation if fallback occurred

See ADR-019: Backend Registry Integration for architectural details.

---

Optional Dependencies

RAW Camera File Support

Enable direct ingestion of professional camera RAW formats such as CR2, NEF, ARW, and DNG.

pip install -e ".[raw]"
# or: pip install rawpy

RAW inputs are auto-detected and converted into pipeline-ready RGB using LibRaw via rawpy. If ./.venv-raw/bin/python exists, Lux Depth V3 auto-discovers that repo-local RAW runtime before falling back to the main repo environment.

Recommended (RAW via isolated runtime):

./scripts/setup/install_raw_runtime.sh

lux-depth-v3 --input-dir ./input --output-dir ./output

Use --raw-python only when you want to override that repo-local runtime explicitly:

lux-depth-v3 --input-dir ./input --output-dir ./output --raw-python ~/venvs/raw/bin/python

See SETUP_GUIDE.md for environment details.

---

Depth Pro (Experimental)

Use depth_pro when you need metric depth and are operating in an explicit research-only workflow.

mkdir -p checkpoints
curl -L https://ml-site.cdn-apple.com/models/depth-pro/depth_pro.pt -o checkpoints/depth_pro.pt
./scripts/setup/install_depth_pro_runtime.sh

Keep depth-pro in its own environment. Its dependency constraints conflict with the main repository stack, and the repo-owned setup script pins the known-good Depth Pro runtime surface (torch==2.7.1, torchvision==0.22.1, numpy==1.26.4) that restores MPS readiness on current macOS 26.x pip-wheel hosts.

Required CLI wiring:

lux-depth-v3 \
  --input-dir ./input \
  --output-dir ./output \
  --depth-backend depth_pro \
  --depth-pro-python ./.venv-depth-pro/bin/python \
  --non-commercial-ok true \
  --accept-apple-depth-pro-research-license true

# Or export once for repeated runs
export TRANSFORMATION_PORTAL_DEPTH_PRO_PYTHON=./.venv-depth-pro/bin/python

See the Lux Depth V3 CLI Guide for presets, Apple Silicon guidance, and license enforcement details.

---

PBR Map Generation

Lux Depth V3 can generate physically based rendering maps directly from the full pipeline or from cached depth when you are tuning look-development workflows.

Fast PBR-only run:

lux-depth-v3 \
  --input-dir ./input \
  --output-dir ./output/pbr \
  --quality-tier apex \
  --pbr "on" \
  --enable-v2 "off"

Typical outputs:

• *_depth.png and optional float depth artifacts
• *_normal.png
• *_roughness.png
• *_ao.png

For standalone depth-to-PBR iteration, see PBR Processor Quick Start.

---

Quick Start

Recommended local setup:

git clone https://github.com/RC219805/Transformation_Portal.git
cd Transformation_Portal
make venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
make install-core
make check-environment
lux-depth-v3 --help

Core-only installs are useful for documentation, contract checks, portal/orchestrator surfaces, and non-ML utilities. Actual depth inference with the default da3 backend requires the ML tier unless you are intentionally exercising synthetic fallback in a constrained test setup.

Add a trusted ML profile when you need DA3 depth inference, research backends, segmentation, or other model-heavy workflows:

make install-ml-core
# or use the target-specific bootstrap flow:
./scripts/bootstrap/install_ml_stack.sh --profile core-cpu
make test-fast

The umbrella ML install path is intentionally disabled until a trusted checked-in umbrella lockfile contract exists again.

For a more guided environment bring-up, see SETUP_GUIDE.md.

---

Machine-Readable JSON Output for Automation

The metadata extraction tooling supports deterministic machine-mode JSON for CI/CD and automation.

python scripts/test_metadata_extraction.py --json extract /input/image.CR2

Key properties:

• deterministic structure and stable keys
• explicit exit-code semantics
• schema-versioned payloads for automation

Docs:

• Machine Mode JSON Quick Reference
• Machine Mode Contract

---

Dependency Management

• Root requirements*.txt files are convenience entry points.
• requirements/ contains the layered source of truth for maintainers.
• If you change dependency inputs, regenerate and commit the matching lockfiles from requirements/.

See AGENTS.md and the requirements/ Make targets for the supported lock/update workflow.

---

Repository Layout (high level)

• src/ installable package source
• docs/ architecture, guides, contracts, and reports
• scripts/ operational workflows, validation, and setup helpers
• tests/ pytest suite and regression gates
• config/ presets and pipeline configuration
• tools/ developer and audit utilities

---

Supported File Formats (summary)

• Images: PNG, JPEG, TIFF, WebP, BMP
• RAW stills: optional via rawpy for major camera ecosystems
• Video: MP4, MOV, AVI, MKV where FFmpeg codec support is available
• High-bit-depth and metadata-preserving workflows are supported where the selected pipeline path and dependencies allow

---

System Requirements

• Python 3.11+
• CPU-only operation supported
• Apple Silicon (mps) and CUDA acceleration supported where the selected workflow can use them
• FFmpeg recommended for video workflows

---

Testing

Use the Make targets first:

make test-fast
make test-full
make ci
make test-orchestrator-contract
make test-frontdoor-contract
make seed-frontdoor-user
make validate-orchestrator-http
make validate-portal-browser
make validate-frontdoor-browser
make run-frontdoor-local
make audit-pipeline-readiness

Readiness and validation tiers:

• make test-orchestrator-contract keeps the portal/orchestrator contract suite local and deterministic.
• make test-frontdoor-contract keeps the managed front-door Node contract/build gate deterministic under Node 22.x.
• make seed-frontdoor-user writes the canonical local managed-frontdoor credential fixture to /tmp/tp-frontdoor-users.json using smoke-admin / correct horse battery staple unless you override the frontdoor credential env vars.
• make validate-orchestrator-http runs the live backend smoke against a running FastAPI origin.
• make validate-portal-browser launches an isolated local backend, then runs the live portal browser smoke and fails early if /v1/config-preview cannot authenticate or validate.
• make validate-frontdoor-browser launches isolated local backend and managed front-door runtimes, auto-seeds the canonical local smoke credentials for that ephemeral runtime, and then runs the live browser smoke against the managed proof setup.
• make run-frontdoor-local starts the canonical managed front door on http://localhost:3000, auto-seeds the same canonical local user fixture when no explicit frontdoor user source is configured, and refuses to fall back to :3001.
• make audit-pipeline-readiness runs the safe local four-pipeline readiness audit and reports ready / degraded / blocked outcomes, including separate lux-depth-v3 base vs canary status.

Direct pytest examples:

pytest -v tests/ -ra -m "not ml and not slow" --maxfail=1
pytest -v tests/ -ra -m "ml and not slow" --maxfail=1

---

Performance Monitoring

Performance is treated as a first-class signal in CI.

• APEX workflows publish performance summaries and dashboard updates on main
• Determinism and contract gates protect reproducibility, not just raw throughput
• Local baseline capture and comparison are available through the performance ledger tooling

For deeper performance workflows, see:

• Performance Monitoring Guide
• APEX Real Pipeline Integration Guide
• ADR-024

---

Documentation

Start here:

• Documentation Map
• Setup Guide
• Architecture Overview
• Lux Depth V3 CLI Guide
• Lux Depth V3 Troubleshooting
• API Documentation

---

License

This repository is distributed under a proprietary, limited non-commercial evaluation license. Public visibility does not make it open source.

Repository-level restrictions include:

• No commercial use without prior written authorization
• No redistribution or derivative works
• No ML training, benchmarking, extraction, or reuse of repository materials beyond permitted evaluation use

Component-specific terms may add further restrictions for optional integrations:

• DA3 research preset (depth-anything-v3.1-research-m4): CC BY-NC 4.0
• Apple Depth Pro (depth_pro): Apple AMLR research license with explicit acceptance flags

For exact legal terms, see LICENSE.

---

Support and Contact

Author: Richard Cheetham Brand: Carolwood Estates · RACLuxe Division Email: info@racluxe.com

Resources:

• GitHub Issues: bug reports and feature requests
• Documentation: docs/
• Examples: examples/

---

Last Updated: 2026-03-13