Sync from GitHub: afccd22ead9934714bd8ff3d1eb163ab347878a3

README.md

@@ -5,6 +5,7 @@ colorFrom: blue
 colorTo: purple
 sdk: gradio
 sdk_version: "4.44.0"
+python_version: "3.10"
 app_file: app.py
 pinned: false
 license: apache-2.0
@@ -19,7 +20,7 @@ Optimized Python package for RGB-D depth refinement using Vision Transformer enc
 [![PyPI downloads](https://img.shields.io/pypi/dm/rgbd-depth.svg)](https://pypi.org/project/rgbd-depth/)
 [![Hugging Face Spaces](https://img.shields.io/badge/🤗%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Aedelon/rgbd-depth)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![PyTorch 2.0+](https://img.shields.io/badge/PyTorch-2.0+-red.svg)](https://pytorch.org/)
 
 ## 🎮 Try it Online
@@ -115,21 +116,38 @@ For production workflows or faster inference, use the local installation below.
 
 ### From PyPI (recommended)
 
+**Basic installation (core dependencies only):**
 ```bash
-# Basic installation
 pip install rgbd-depth
+```
 
-# With CUDA optimizations (xFormers)
+**Installation with extras:**
+```bash
+# With CUDA optimizations (xFormers, ~8% faster)
 pip install rgbd-depth[xformers]
 
-# Development installation
+# With Gradio demo interface
+pip install rgbd-depth[demo]
+
+# With HuggingFace Hub model downloads
+pip install rgbd-depth[download]
+
+# With development tools (pytest, black, ruff, etc.)
+pip install rgbd-depth[dev]
+
+# Install everything (all extras)
+pip install rgbd-depth[all]
+```
+
+**Development installation (editable):**
+```bash
 git clone https://github.com/Aedelon/rgbd-depth.git
 cd rgbd-depth
-pip install -e .
+pip install -e ".[dev]"  # or uv sync --extra dev
 ```
 
 **Requirements:**
-- Python 3.8+
+- Python 3.10+ (Python 3.8-3.9 support dropped in v1.0.2+)
 - PyTorch 2.0+ with appropriate CUDA/MPS support
 - OpenCV, NumPy, Pillow
 
@@ -264,18 +282,53 @@ We currently provide pre-trained models available for:
 ## File Structure
 
 ```
-cdm/
-├── infer.py              # Main inference script
-├── setup.py              # Package installation
-├── rgbddepth/            # Core package
-│   ├── __init__.py
-│   ├── dpt.py            # Main RGBDDepth model
-│   ├── dinov2.py         # DINOv2 encoder
-│   ├── dinov2_layers/    # ViT transformer layers
-│   └── util/             # Utility functions
-│       ├── blocks.py     # Neural network blocks
-│       └── transform.py  # Image preprocessing
-└── README.md
+rgbd-depth/
+├── app.py                      # Gradio web demo for HuggingFace Spaces
+├── infer.py                    # CLI inference script (main entry point)
+├── pyproject.toml              # Modern package config (PEP 621, replaces setup.py)
+├── setup.py                    # Legacy setuptools build script
+├── requirements.txt            # Minimal deps for HuggingFace Spaces
+├── uv.lock                     # UV package manager lock file
+├── LICENSE                     # Apache 2.0 license
+├── README.md                   # This file (GitHub/PyPI/HF Spaces unified)
+├── OPTIMIZATION.md             # Performance benchmarks and optimization guide
+├── CHANGELOG.md                # Version history and release notes
+└── VIRAL_STRATEGY.md           # GitHub/PyPI marketing strategy
+│
+├── rgbddepth/                  # Main Python package
+│   ├── __init__.py             # Public API exports (RGBDDepth, DinoVisionTransformer, __version__)
+│   ├── dpt.py                  # RGBDDepth model (dual-branch ViT + DPT decoder)
+│   ├── dinov2.py               # DINOv2 Vision Transformer encoder
+│   ├── flexible_attention.py   # Cross-attention w/ xFormers + SDPA fallback
+│   │
+│   ├── dinov2_layers/          # Vision Transformer building blocks (from Meta DINOv2)
+│   │   ├── __init__.py
+│   │   ├── attention.py        # Self-attention w/ optional xFormers (MemEffAttention)
+│   │   ├── block.py            # Transformer encoder block (NestedTensorBlock)
+│   │   ├── mlp.py              # Feed-forward network (Mlp)
+│   │   ├── patch_embed.py      # Image → patch embeddings (PatchEmbed)
+│   │   ├── swiglu_ffn.py       # SwiGLU activation FFN
+│   │   ├── drop_path.py        # Stochastic depth regularization
+│   │   └── layer_scale.py      # LayerScale normalization
+│   │
+│   └── util/                   # Utilities
+│       ├── __init__.py
+│       ├── blocks.py           # DPT decoder blocks (FeatureFusionBlock, ResidualConvUnit)
+│       └── transform.py        # Image preprocessing (Resize, PrepareForNet)
+│
+├── tests/                      # Test suite (42 tests, runs in GitHub Actions)
+│   ├── test_import.py          # Basic imports and smoke tests
+│   └── test_model.py           # Architecture, forward pass, attention, preprocessing
+│
+├── example_data/               # Example RGB-D pairs for testing
+│   ├── color_12.png            # RGB image sample
+│   ├── depth_12.png            # Depth map sample
+│   └── result.png              # Expected output
+│
+└── .github/workflows/          # CI/CD automation
+    ├── test.yml                # Run tests on Python 3.10-3.12 (Ubuntu/macOS/Windows)
+    ├── publish.yml             # Auto-publish to PyPI on release tags
+    └── deploy-hf.yml           # Auto-deploy to HuggingFace Spaces on push to main
 ```
 
 ## Performance
@@ -292,25 +345,12 @@ CDMs achieve state-of-the-art performance on metric depth estimation:
 - Zero-shot generalization across different camera types
 - Real-time inference suitable for robot control (lightweight ViT variants)
 
-### Speed Benchmarks
-
-| Device | Mode | Precision | Time | vs Baseline | Notes |
-|--------|------|-----------|------|-------------|-------|
-| **CUDA** | Vanilla | FP32 | TBD | - | Reference |
-| **CUDA** | Optimized (xFormers) | FP32 | TBD | ~8% faster | Recommended |
-| **CUDA** | Optimized | FP16 | TBD | ~2× faster | Best speed |
-| **CUDA** | Optimized | BF16 | TBD | ~2× faster | Best stability |
-| **MPS** | Vanilla | FP32 | 1.34s | - | torch.compile: no gain |
-| **MPS** | Vanilla | FP16 | TBD | TBD | To be benchmarked |
-| **CPU** | Vanilla | FP32 | 13.37s | - | Optimizations: -11% slower |
-
-**Notes:**
-- **CUDA**: Optimizations auto-enabled by default (use `--no-optimize` to disable)
-- **MPS**: torch.compile provides no gain for Vision Transformers (~0% improvement)
-- **CPU**: torch.compile is counterproductive (compilation overhead > gains)
-- xFormers is CUDA-only (~8% faster than native SDPA)
-
-For detailed optimization strategies, see [OPTIMIZATION.md](OPTIMIZATION.md).
+**Performance optimizations:**
+- xFormers support on CUDA (~8% faster than native SDPA)
+- Mixed precision (FP16/BF16) for faster inference
+- Device-specific optimizations (CUDA/MPS/CPU)
+
+For detailed optimization strategies and benchmarks, see [OPTIMIZATION.md](OPTIMIZATION.md).
 
 ## What's Different from Reference?
 

app.py

@@ -4,6 +4,7 @@
 
 """Gradio demo for rgbd-depth on Hugging Face Spaces."""
 
+import logging
 from pathlib import Path
 
 import gradio as gr
@@ -13,6 +14,14 @@ from PIL import Image
 
 from rgbddepth import RGBDDepth
 
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
 # Global model cache
 MODELS = {}
 
@@ -35,16 +44,16 @@ def download_model(camera_model: str = DEFAULT_MODEL):
         from huggingface_hub import hf_hub_download
 
         repo_id, filename = HF_MODELS.get(camera_model, HF_MODELS[DEFAULT_MODEL])
-        print(f"📥 Downloading {camera_model} model from {repo_id}/{filename}...")
+        logger.info(f"Downloading {camera_model} model from {repo_id}/{filename}...")
 
         # Download the checkpoint
         checkpoint_path = hf_hub_download(repo_id=repo_id, filename=filename, cache_dir=".cache")
 
-        print(f"✓ Downloaded to {checkpoint_path}")
+        logger.info(f"Downloaded to {checkpoint_path}")
         return checkpoint_path
 
     except Exception as e:
-        print(f"❌ Failed to download model: {e}")
+        logger.error(f"Failed to download model: {e}")
         return None
 
 
@@ -70,7 +79,7 @@ def load_model(camera_model: str = DEFAULT_MODEL, use_xformers: bool = False):
         local_path = Path(f"checkpoints/{camera_model}.pt")
         if local_path.exists():
             checkpoint_path = str(local_path)
-            print(f"✓ Using local checkpoint: {checkpoint_path}")
+            logger.info(f"Using local checkpoint: {checkpoint_path}")
         else:
             # 2. Download from HuggingFace
             checkpoint_path = download_model(camera_model)
@@ -87,11 +96,13 @@ def load_model(camera_model: str = DEFAULT_MODEL, use_xformers: bool = False):
                     states = checkpoint
 
                 model.load_state_dict(states, strict=False)
-                print(f"✓ Loaded checkpoint for {camera_model}")
+                logger.info(f"Loaded checkpoint for {camera_model}")
             except Exception as e:
-                print(f"⚠ Failed to load checkpoint: {e}, using random weights")
+                logger.warning(f"Failed to load checkpoint: {e}, using random weights")
         else:
-            print(f"⚠ No checkpoint available for {camera_model}, using random weights (demo only)")
+            logger.warning(
+                f"No checkpoint available for {camera_model}, using random weights (demo only)"
+            )
 
         # Move to GPU if available (CUDA or MPS for macOS)
         if torch.cuda.is_available():
@@ -167,13 +178,13 @@ def process_depth(
         else:
             dtype = None  # FP32
 
-        # DEBUG: Print input stats
-        print(f"[DEBUG] depth_image raw: min={depth_image.min():.1f}, max={depth_image.max():.1f}")
-        print(
-            f"[DEBUG] depth_normalized: min={depth_normalized[depth_normalized>0].min():.4f}, max={depth_normalized.max():.4f}"
+        # Log input statistics
+        logger.debug(f"depth_image raw: min={depth_image.min():.1f}, max={depth_image.max():.1f}")
+        logger.debug(
+            f"depth_normalized: min={depth_normalized[depth_normalized>0].min():.4f}, max={depth_normalized.max():.4f}"
         )
-        print(
-            f"[DEBUG] simi_depth: min={simi_depth[simi_depth>0].min():.4f}, max={simi_depth.max():.4f}"
+        logger.debug(
+            f"simi_depth: min={simi_depth[simi_depth>0].min():.4f}, max={simi_depth.max():.4f}"
         )
 
         # Run inference
@@ -184,14 +195,14 @@ def process_depth(
         else:
             pred = model.infer_image(rgb_image, simi_depth, input_size=input_size)
 
-        # DEBUG: Print prediction stats before reconversion
-        print(f"[DEBUG] pred (inverse depth): min={pred[pred>0].min():.4f}, max={pred.max():.4f}")
+        # Log prediction statistics
+        logger.debug(f"pred (inverse depth): min={pred[pred>0].min():.4f}, max={pred.max():.4f}")
 
         # Convert from inverse depth to depth
         pred = np.where(pred > 1e-8, 1.0 / pred, 0.0)
 
-        # DEBUG: Print final depth stats
-        print(f"[DEBUG] pred (depth): min={pred[pred>0].min():.4f}, max={pred.max():.4f}")
+        # Log final depth statistics
+        logger.debug(f"pred (depth): min={pred[pred>0].min():.4f}, max={pred.max():.4f}")
 
         # Colorize for visualization
         try: