Onboarding: sjmoran/deeplpf-image-enhancement

Generated by RepoPilot · 2026-05-05 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Read in the suggested order before editing unfamiliar code. The reading-order list is computed from the actual import graph, not LLM guesses; reading bottom-up materially reduces wrong-edit risk.
3. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
4. Cite source on changes. When proposing an edit, cite the specific path/to/file.ext:Lstart-Lend you're reasoning about, the same way RepoPilot's own RAG cites code in https://repopilot.app/r/sjmoran/deeplpf-image-enhancement.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

AVOID — Stale and unlicensed — last commit 2y ago

• 4 active contributors
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 4 top contributors
• ⚠ Concentrated ownership — top contributor handles 64% of commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ No test directory detected
• ⚠ Scorecard: marked unmaintained (0/10)
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sjmoran/deeplpf-image-enhancement repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sjmoran/deeplpf-image-enhancement.

What it runs against: a local clone of sjmoran/deeplpf-image-enhancement — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sjmoran/deeplpf-image-enhancement | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 658 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>sjmoran/deeplpf-image-enhancement</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sjmoran/deeplpf-image-enhancement. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sjmoran/deeplpf-image-enhancement.git
#   cd deeplpf-image-enhancement
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sjmoran/deeplpf-image-enhancement and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sjmoran/deeplpf-image-enhancement(\\.git)?\\b" \\
  && ok "origin remote is sjmoran/deeplpf-image-enhancement" \\
  || miss "origin remote is not sjmoran/deeplpf-image-enhancement (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "main.py" \\
  && ok "main.py" \\
  || miss "missing critical file: main.py"
test -f "model.py" \\
  && ok "model.py" \\
  || miss "missing critical file: model.py"
test -f "unet.py" \\
  && ok "unet.py" \\
  || miss "missing critical file: unet.py"
test -f "data.py" \\
  && ok "data.py" \\
  || miss "missing critical file: data.py"
test -f "metric.py" \\
  && ok "metric.py" \\
  || miss "missing critical file: metric.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 658 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~628d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sjmoran/deeplpf-image-enhancement"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

Suggested reading order

Computed from the actual import graph (no LLM). Read in this order to learn the codebase from the foundation up — each step builds on the previous ones.

1. util.py — Foundation: doesn't import anything internally and is imported by 3 other files. Read first to learn the vocabulary.
2. unet.py — Foundation: imported by 1, no internal dependencies of its own.
3. model.py — Built on the foundation; imported by 1 downstream file.
4. data.py — Built on the foundation; imported by 1 downstream file.
5. main.py — Layer 2 — application-level code that wires the lower layers together.

TL;DR

DeepLPF is a deep learning model for image enhancement that learns spatially-varying local parametric filters to enhance photos. Published at CVPR 2020, it processes raw/underexposed images from Adobe5K dataset and produces enhanced outputs by predicting local filter parameters (e.g., tone curves, color shifts) at each pixel location rather than applying global transformations. Simple flat structure: main.py and data.py at root contain training/inference logic, metric.py handles PSNR/SSIM evaluation, adobe5k_dpe/ contains the Adobe5K dataset split (images_train.txt, images_valid.txt, images_test.txt) with input/output/inference directories showing expected data layout. No src/ or package structure—everything is module-level in the repo root.

Who it's for

Computer vision researchers and practitioners building image enhancement pipelines who want a learnable alternative to traditional manual photo editing; specifically those working with consumer photography datasets like Adobe5K and needing to replicate CVPR 2020 results.

Maturity & risk

This is a research codebase with moderate maturity: it's tied to a published CVPR 2020 paper with reference implementations and pre-trained weights, but the README explicitly warns that batch size >1 is unsupported and requires re-engineering. The codebase appears maintenance-mode (implementation reference rather than production framework), with example test images and inference outputs provided but no visible CI/test suite in file structure.

Key risks: (1) Hard constraint on batch_size=1 limits scalability and requires manual re-engineering for production use, (2) Dependencies are pinned to 2020-era PyTorch 1.7.1 and may conflict with modern Python/CUDA, (3) Single-author repository with no visible issue tracker or pull request activity, (4) No automated tests visible in file listing suggests validation is manual against example images.

Active areas of work

This appears to be a static research artifact (snapshot of paper implementation). The repo contains example test inference results with recorded metrics (e.g., 'a4576-DSC_0217_TEST_425_9_PSNR_34.596_SSIM_0.980.jpg') and example input/output pairs, suggesting it is stable and not actively developing new features.

Get running

git clone https://github.com/sjmoran/deeplpf-image-enhancement.git
cd deeplpf-image-enhancement
pip install numpy==1.22.0 torch==1.7.1 torchvision==0.8.2 scikit-image==0.18.1 scipy==1.10.0 pillow>=8.3.2 matplotlib==3.3.2 imageio==2.9.0
python main.py  # Check README for specific args (training vs. inference mode)

Daily commands: No Makefile visible. Based on structure, inference likely: python main.py --input_image adobe5k_dpe/deeplpf_example_test_input/a4576-DSC_0217_input.png --model_path <pretrained_weights> --output_dir adobe5k_dpe/deeplpf_example_test_output/. For training: python main.py --mode train --batch_size 1 --dataset_path adobe5k_dpe/ --train_file images_train.txt. Check main.py argparse for exact flags.

Map of the codebase

• main.py — Entry point for training and inference; orchestrates the complete pipeline including data loading, model initialization, and evaluation loops
• model.py — Defines the DeepLPF neural network architecture including the core local parametric filter generation mechanism
• unet.py — Implements the U-Net backbone encoder-decoder that generates local filter parameters; critical to the model's feature extraction
• data.py — Handles dataset loading, preprocessing, and augmentation for Adobe5K and other datasets; data pipeline foundation
• metric.py — Computes PSNR and SSIM metrics for training and evaluation; validation metric calculations
• util.py — Utility functions for image I/O, tensor conversions, and helper operations used throughout the codebase

Components & responsibilities

• U-Net Backbone (unet.py) (PyTorch nn.Module, Conv2d, BatchNorm2d, ReLU, upsampling) — Extracts multi-scale features from input image via encoder-decoder path; outputs feature maps that are decoded into local filter parameters
  • Failure mode: Poor feature extraction or spatial detail loss → degraded enhancement quality; misaligned skip connections → feature map dimension mismatch
• DeepLPF Model (model.py) (PyTorch nn.Module, Conv2d, learnable parameters) — Orchestrates U-Net backbone and local parametric filter application; predicts spatially-varying filter kernels and applies them to enhance input images
  • Failure mode: Filter parameter predictions out-of-range → numerical instability; incorrect kernel application → visual artifacts; dimension mismatch with U-Net output
• Data Pipeline (data.py) (torch.utils.data.Dataset/DataLoader, PIL,) — Loads image pairs, applies normalization, handles train/valid/test splits; provides consistent batch iteration for main.py

How to make changes

Add Support for a New Dataset

1. Create a new dataset class in data.py that inherits from torch.utils.data.Dataset, implementing getitem to load and return (input_image, target_image) pairs (data.py)
2. Register the dataset loader in main.py by adding a conditional branch in the data loading section and creating corresponding train/valid/test split files (main.py)
3. Update command-line arguments in main.py to accept the new dataset name via --dataset flag (main.py)

Train DeepLPF on Custom Data

1. Prepare input and target image pairs; create train/valid/test split text files listing image paths in adobe5k_dpe/ directory structure (adobe5k_dpe/images_train.txt)
2. Configure training hyperparameters in main.py including batch_size (must be 1), learning_rate, epochs, and model checkpoint frequency (main.py)
3. Execute main.py with --dataset, --train_dir, --test_dir flags to begin training; model checkpoints save automatically during validation (main.py)

Add a New Loss Function or Regularization

1. Define the new loss computation as a method or function in model.py, accepting network output and ground-truth target images (model.py)
2. Integrate the new loss into the training loop in main.py, either by replacing or combining with existing L1 loss on the final enhanced image output (main.py)
3. Update the backward pass and optimizer step to use the modified loss; log loss values for monitoring (main.py)

Modify the U-Net Backbone Architecture

1. Edit unet.py to change encoder/decoder layer counts, channel dimensions, kernel sizes, or add skip connection modifications (unet.py)
2. Update model.py if the output tensor shape or dimension changes, ensuring it still matches the expected local filter parameter grid size (model.py)
3. Retrain from scratch or fine-tune existing checkpoints; validate PSNR/SSIM metrics in main.py evaluation loop (main.py)

Why these technologies

• PyTorch (torch==1.7.1, torchvision==0.8.2) — Dynamic computational graphs enable efficient local parametric filter generation and gradient computation during training; well-suited for image-to-image enhancement tasks
• U-Net (defined in unet.py) — Encoder-decoder with skip connections preserve spatial detail while learning hierarchical features; standard for image-to-image translation in enhancement pipelines
• NumPy & SciPy (numpy==1.22.0, scipy==1.10.0) — Efficient numerical computation and matrix operations for image processing and metric calculations
• scikit-image (scikit_image==0.18.1) — SSIM metric implementation and image preprocessing utilities

Trade-offs already made

• Batch size fixed at 1 during training and inference

  • Why: Local parametric filters require per-pixel parameter generation with spatial localization; batch processing introduces complexity in filter application and memory management
  • Consequence: Slower training and inference throughput; cannot exploit modern GPU parallelization; must be re-engineered to support higher batch sizes

• L1 loss on final enhanced output (no perceptual or adversarial losses)

  • Why: Simple, stable, and directly optimizes pixel-level reconstruction quality; reproducible results
  • Consequence: May produce less visually appealing results compared to perceptual losses; potential for over-smoothing in edge regions

• Local parametric filters applied via learned kernels rather than end-to-end global transformation

  • Why: Enables interpretable, spatially-varying enhancement; captures local context-dependent adjustments
  • Consequence: Higher computational cost per pixel compared to global enhancement; requires careful parameter grid design

Non-goals (don't propose these)

• Real-time inference (batch size = 1, no optimization for mobile/embedded deployment)
• Multi-GPU or distributed training support
• Adversarial or perceptual loss training
• Interactive enhancement UI or web interface
• Support for video frame sequences or temporal coherence
• Automatic dataset augmentation beyond basic loading

Traps & gotchas

CRITICAL—Batch size constraint: Code is hard-coded for batch_size=1. Using batch_size>1 will fail silently or produce incorrect results; must re-engineer gather/scatter operations in main.py. | PyTorch version pinning: torch==1.7.1 (Nov 2020) may have CUDA 11.0 compatibility issues on modern systems; may need conda to resolve or build from source. | Data path assumptions: data.py likely assumes images are in adobe5k_dpe/ directory relative to cwd; running from elsewhere breaks file loading. | No model.py: Core model architecture not visible in file listing—may be defined inline in main.py or in a module not listed; check imports in main.py. | Missing pretrained weights: README references 'pre-trained models' but no .pth/.pt files in listing; must download from external link (check GitHub releases or supplementary materials).

Architecture

Concepts to learn

• Local Parametric Filters — Core innovation of DeepLPF—predicting spatially-varying filter parameters per pixel rather than global parameters; fundamental to understanding why this model outperforms global enhancement methods
• Differentiable Image Processing — The filter application must be differentiable so gradients flow from output loss back to predicted filter parameters during backprop; key constraint shaping model design
• Batch Normalization Constraints — The batch_size=1 limitation is often due to BatchNorm layers which require statistics across batch samples; understanding this constraint is essential before modifying the architecture
• Structured Loss Functions (PSNR/SSIM) — Model optimizes PSNR and SSIM (computed in metric.py) which better align with human perception than L2 loss; understanding perceptual metrics is critical for debugging results
• Tone Curve / Lookup Table (LUT) Parameterization — Local parametric filters likely include tone curves or color LUTs as parameters; this is a standard photography editing primitive that DeepLPF learns spatially
• Adobe5K Dataset (DPE splits) — Canonical paired image dataset for enhancement research with expert retouching; understanding the train/valid/test splits in images_*.txt is essential for reproduction
• Encoder-Decoder with Skip Connections — Typical architecture for dense prediction tasks (per-pixel parameter maps); likely used in main.py's model to preserve spatial detail while downsampling for efficiency

Related repos

• chaofengc/Face-Restoration-Benchmark — Similar image enhancement task using deep learning; useful reference for architecture patterns and evaluation against multiple methods
• jiaxy/DeepISP — End-to-end learnable ISP (Image Signal Processing) pipeline; related approach to parameterized image-to-image translation that could inspire local filter extensions
• adobe/Deep-Photo-Enhancer — Adobe's deep learning enhancement baseline on the same Adobe5K dataset; direct competitor for benchmarking and understanding SOTA before DeepLPF
• aiff22/KinD — Concurrent low-light image enhancement work (similar problem domain); good for cross-method comparison and understanding alternative architectures
• sjmoran/CURL — Same author's follow-up work on contrastive learning for image enhancement; natural progression from DeepLPF if exploring this codebase further

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add batch size > 1 support and refactor model.py for variable batch dimensions

The README explicitly states 'this code is designed for a batch size of 1' and 'needs re-engineered to support higher batch sizes'. This is a critical limitation that prevents production use and scaling. The model.py file likely has hardcoded spatial dimension assumptions that break with different batch sizes. Refactoring this would unlock significant value for users and enable faster training.

• [ ] Analyze model.py to identify hardcoded batch size assumptions (e.g., reshape operations, dimension indexing)
• [ ] Refactor local parametric filter application in model.py to use view() or reshape() that preserves batch dimension
• [ ] Update data.py to support configurable batch sizes in data loading and batching logic
• [ ] Add unit tests in a new tests/test_batch_sizes.py validating inference with batch_size=1,2,4,8
• [ ] Test on util.py tensor operations to ensure they don't assume batch size of 1
• [ ] Update README with new batch size support and any performance implications

Add reproducible test suite (test_inference.py) using adobe5k_dpe example data

The repo includes example test input/output data in adobe5k_dpe/deeplpf_example_test_* directories and pretrained models, but no automated test script to validate inference output matches expected results. This makes it impossible for contributors to verify their changes don't break existing functionality. Creating a test suite would catch regressions and provide a reference implementation.

• [ ] Create tests/test_inference.py that loads pretrained_models/adobe_dpe/deeplpf_validpsnr_*.pt
• [ ] Implement test cases that run inference on adobe5k_dpe/deeplpf_example_test_input/*.png images
• [ ] Compare output PSNR/SSIM metrics (parsed from filenames) against reference values in adobe5k_dpe/deeplpf_example_test_inference/
• [ ] Add assertions allowing ±0.5 PSNR tolerance to account for minor numerical differences across systems
• [ ] Create a pytest configuration (pytest.ini) and update requirements.txt to include pytest and pytest-cov
• [ ] Document test running instructions in README under a 'Testing' section

Add configuration file support and remove hardcoded hyperparameters from main.py

main.py likely contains scattered hardcoded values for learning rate, epochs, optimizer settings, and model architecture choices. Adding a YAML/JSON config file system (parsed by util.py or a new config.py module) would make experiments reproducible, enable quick parameter sweeps, and make the codebase more maintainable. This is evidenced by the diverse pretrained models (adobe_dpe, adobe_upe, adobe_distort_and_recover) which likely required manual code changes to train.

• [ ] Create config/default.yaml with sections: [model, training, data, optimization, inference] containing all hyperparameters from main.py
• [ ] Add a new config.py module that parses YAML using PyYAML (add to requirements.txt)
• [ ] Refactor main.py to load config from file and use config dict instead of hardcoded values
• [ ] Create separate config files: config/adobe_dpe.yaml, config/adobe_upe.yaml, config/adobe_distort_and_recover.yaml matching the pretrained models
• [ ] Update main.py to accept --config argument: python main.py --config config/adobe_dpe.yaml
• [ ] Document config file structure and all parameters in README under 'Configuration' section

Good first issues

• Add unit tests for metric.py's PSNR and SSIM functions by testing against known image pairs (e.g., identical images should yield PSNR=∞, SSIM=1.0); currently no test suite visible.
• Document the exact dataset format expected by data.py by adding a DATASET_SETUP.md with examples of how to structure custom Adobe5K-style image pairs (input/.png, gt/.png layout); helps users onboard new datasets.
• Create a batch_size>1 compatibility patch by refactoring the parametric filter application in main.py to support batched operations; start with identifying the gather/scatter operations that break under batching and wrap them in a compatibility layer.

Top contributors

• @sjmoran — 18 commits
• [@Sean Moran](https://github.com/Sean Moran) — 7 commits
• @dependabot[bot] — 2 commits
• @PierreMarza — 1 commits

Recent commits

• e610b2b — Update README.md (PierreMarza)
• 22dbdf8 — Merge pull request #22 from sjmoran/dependabot/pip/scipy-1.10.0 (sjmoran)
• bb6fd7b — Bump scipy from 1.5.2 to 1.10.0 (dependabot[bot])
• 7fd269e — Merge pull request #18 from sjmoran/dependabot/pip/numpy-1.22.0 (sjmoran)
• af3052f — Bump numpy from 1.19.2 to 1.22.0 (dependabot[bot])
• eaea415 — Update README.md (sjmoran)
• 9551718 — Added asserts for batch size (Sean Moran)
• cca80a6 — Merge branch 'master' of https://github.com/sjmoran/DeepLPF (Sean Moran)
• 94292a3 — Added assertion statements for batch size (Sean Moran)
• 1739458 — Update requirements.txt (sjmoran)

Security observations

This research codebase has significant security concerns primarily centered on severely outdated dependencies with known vulnerabilities. The project uses PyTorch, NumPy, and Pillow versions from 2-4 years ago that contain multiple documented CVEs related to arbitrary code execution, buffer overflows, and denial-of-service attacks. Additionally, there is no dependency lock file or vulnerability scanning infrastructure. While the code itself appears to be a legitimate academic project without obvious injection vulnerabilities or hardcoded secrets, the dependency management practices are inadequate for any production use. For a research project, immediate dependency updates and the establishment of a vulnerability management process are critical recommendations.

• High · Outdated and Vulnerable Dependencies — requirements.txt. The project uses significantly outdated dependencies with known security vulnerabilities. numpy==1.22.0 (from Jan 2022), torch==1.7.1 (from Nov 2020), and torchvision==0.8.2 (from Oct 2020) contain multiple known CVEs. These versions are 2-4 years old and have been superseded by patched releases. Fix: Update all dependencies to the latest stable versions. At minimum: numpy>=1.24.0, torch>=2.0.0, torchvision>=0.15.0, scipy>=1.10.0. Review each dependency's changelog for security patches and breaking changes before updating.
• High · Insecure Pillow Dependency Version Constraint — requirements.txt. The pillow>=8.3.2 constraint allows installation of versions with known security issues. Pillow 8.3.2 was released in August 2021 and contains multiple CVEs (CVE-2021-23437, CVE-2021-28957, and others) related to image parsing and buffer overflows. Fix: Update to pillow>=10.0.0 or later. The minimum version should be pinned to a more recent release with all known security patches applied.
• Medium · No Dependency Pinning Strategy — requirements.txt. Most dependencies use loose version constraints (e.g., '==') but pillow uses '>=', allowing transitive dependency issues. Additionally, there's no lock file (requirements.lock or poetry.lock) to ensure reproducible builds across environments, increasing supply chain risk. Fix: Implement a robust dependency management strategy: (1) Use exact pinning (==) for all direct dependencies, (2) Generate and maintain a lock file using pip-tools or Poetry, (3) Regularly audit dependencies for vulnerabilities using tools like Safety or Snyk.
• Medium · Unused/Redundant Dependency — requirements.txt. The package 'skimage==0.0' appears to be a placeholder or corrupted entry. This version number is invalid and will likely cause installation failures. scikit-image is already specified separately. Fix: Remove the 'skimage==0.0' entry from requirements.txt as it conflicts with 'scikit_image==0.18.1' and serves no purpose.
• Low · Missing Input Validation Framework — data.py, util.py. The codebase handles image data loading and processing (data.py, util.py) but there's no visible input validation or sanitization. While this is primarily a research project, processing untrusted image files without validation could lead to denial-of-service or unexpected behavior. Fix: Implement input validation for image files: (1) Validate file types and magic bytes, (2) Check image dimensions against reasonable limits, (3) Use try-catch blocks for image parsing, (4) Sanitize file paths to prevent directory traversal attacks.
• Low · No Security Documentation — Repository root. The repository lacks security guidelines, responsible disclosure policy, or security-related documentation. There's no SECURITY.md file or guidance on reporting vulnerabilities. Fix: Create a SECURITY.md file outlining: (1) How to report security issues responsibly, (2) Security considerations for users, (3) Known limitations and assumptions, (4) Guidelines for code review and contribution.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.