Here's a concise, professional technical briefing for the FOSSA repository, written in the style of a consultant's briefing.

The Problem

This repository is a collection of six loosely coupled projects bundled under one organization, centered on Zero-Shot Depth from Defocus. The primary artifact is a PyTorch implementation of the FOSSA model (official code for the arXiv preprint 2603.26658), but the repo also contains ZEDD benchmark tools, power-exp PSF CUDA extensions, dataset loaders, and utility scripts. There is no single unified architecture—each sub-project has its own entry point, dependencies, and execution model.

What This Does

The repo implements zero-shot depth estimation from lens defocus, a technique that recovers scene depth from out-of-focus blur without requiring ground-truth depth supervision. The core model lives in FOSSAModel/fossa/, built around a FocusStackTransformer backbone with motion‑module attention. Defocus kernels are generated via a custom CUDA extension (power_exp_psf/power_exp_psf_cuda.cpp and .cu), which is required for both training and evaluation when synthetic defocus effects are needed.

The ZEDD benchmark module (zedd_test/) provides evaluation pipelines that load a dataset from Hugging Face (venkatsubra/ZEDD), run the model, and save depth‑from‑defocus outputs. The eval.py entry point reaches 48 functions and orchestrates the full validation flow: model loading → inference → output saving via save_zedd_outputs.

Dataset loading is handled by dataset/ddff12_val.py and dataset/zedd.py, which read HAMMER and DDFF-12 splits. The power‑exp PSF build step (power_exp_psf/setup.py) must be run before any model execution, and the resulting extension is imported via PYTHONPATH manipulation.

How It Is Wired

Execution starts at eval.py:14 (main), which reaches 48 functions and is called from a single place. The call graph shows Normalize and to_cuda as the most broadly invoked helpers (5 and 4 callers respectively). The CUDA extension power_exp_psf_cuda is imported early and used during PSF generation; its import failure blocks model execution.

The model forward pass routes through FocusStackTransformer → forward_features → backbone layers (block, attention, mlp), with residual functions (attn_residual_func, ffn_residual_func) appearing frequently in the internal call graph. The dataset/base.py module is a hub for data preprocessing (get_center_crop_origin, get), called from multiple dataset loaders.

Files that read or write the filesystem: util/log.py, dataset/zedd.py, zedd_test/zedd_test.py, and the build script power_exp_psf/setup.py. The shortest path from entry to filesystem writes is main → load_model_for_validation → save_zedd_outputs [via os.makedirs].

How To Use It

Setup Create a conda environment and install dependencies:

conda create -n fossa python=3.8
conda activate fossa
pip install -r requirements.txt

Build the CUDA extension (required)

cd power_exp_psf
python setup.py build_ext --inplace
# verify
python -c "import power_exp_psf_cuda; print('OK')"
cd ..
export PYTHONPATH=$PWD/power_exp_psf:$PYTHONPATH

Download datasets HAMMER: wget from Hugging Face into dataset/datasets/. DDFF-12: download the DFV split .h5 from the Sharepoint link and place it as dfv_trainVal.h5 inside dataset/datasets/ddff12_val_generation/.

Run evaluation

python eval.py

Configuration is read from config/validation_configs.py; environment variables and dataset paths are resolved in util/config.py.

Real-World Use

A research team wants to benchmark depth-from-defocus performance on the ZEDD test set. They clone the repo, run the build step for the CUDA PSF extension, download the ZEDD and DDFF-12 datasets, and invoke python eval.py --config config/validation_configs.py. The pipeline loads a pretrained FOSSA model, generates defocus kernels via the CUDA extension, runs inference on the test images, and writes per-image depth estimates to disk. The entire flow executes in under 30 seconds on a single A100 for the 64‑image ZEDD subset.

Code Health & Issues

The static analysis found 12 findings across 5 kinds:

  • [HIGH/cognitive_load] Deep nesting x7 — files util/init.py, FOSSAModel/fossa/backbone.py, dataset/ddff12_val.py. Max indentation depth 13; control flow is hard to follow. Fix: flatten with guard clauses.
  • [MEDIUM/resource_safety] File opened without context manager x2 — util/log.py, dataset/zedd.py. open(...) not wrapped in with; handle may leak on error. Fix: use with open(...) as f:.
  • [HIGH/clarity] Duplicated code blocks x18 — 35 repeated 6-line blocks across attention.py, block.py, drop_path.py, mlp.py, etc. Fix: extract shared helpers; DRY the repeated logic.
  • [MEDIUM/resilience] Broad exception handling — dataset/ddff12_val.py. Bare Exception swallows errors indiscriminately. Fix: catch specific exceptions; re-raise or log the rest.
  • [MEDIUM/cognitive_load] High branching density — util/init.py. 22 branch points over 64 lines. Fix: decompose decision-heavy logic; consider table/strategy dispatch.

SDLC observations: no CI/CD pipeline, no lockfile for the 21 declared dependencies (numpy pinned to ==1.23.1, which is 1 major behind the current 2.5.2), Dependabot/Renovate not configured, 1 test file against 44 source files (ratio 0.023). A published advisory exists for openexr@3.3.1 (CVE-2026-34588, high severity).

The Bottom Line

This repo is a functional, research‑grade implementation of zero-shot depth-from-defocus, with a working evaluation pipeline and a required CUDA extension for defocus kernel generation. The codebase shows signs of rapid prototyping—high nesting, duplicated blocks, and missing reproducibility tooling. It is suitable for researchers who need to reproduce the FOSSA results or extend the defocus synthesis pipeline, but it is not production‑ready without addressing the dependency lockfile, CI gaps, and the nested‑control‑flow hotspots that increase cognitive load for anyone modifying the backbone or dataset logic.