AVOID — Stale and unlicensed — last commit 2y ago

• 4 active contributors
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 64% of recent 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}

DeepLPF is a PyTorch-based deep learning model for image enhancement that learns local parametric filters to enhance underexposed/poorly-lit photographs. It predicts per-pixel filter parameters (curves, gains, color shifts) rather than outputting images directly, enabling interpretable and efficient enhancement that matches professional editing workflows. Core capability: trains on Adobe5K dataset pairs (input/reference images) to predict spatially-varying filter parameters that transform low-quality photos to publication-ready quality. Monolithic structure: main.py is the entry point (training/inference orchestrator), data.py handles Adobe5K dataset loading and preprocessing, metric.py computes PSNR/SSIM evaluation metrics. Model architecture code not explicitly listed but inferred to live in unshown .py files in root. Training data organization: adobe5k_dpe/ folder contains input images (deeplpf_example_test_input/), ground-truth enhancements (deeplpf_example_test_output/), and inference results (deeplpf_example_test_inference/) with accompanying .txt split files (images_train.txt, images_valid.txt, images_test.txt).

Computer vision researchers and ML engineers working on image enhancement, particularly those studying low-level vision tasks or parametric image processing. Also useful for photographers and photo editing software developers who need automated enhancement that's interpretable (filter parameters are human-readable) and fast (parameter prediction is cheaper than full image synthesis).

Mature research code tied to a published CVPR 2020 paper with pre-trained weights and example inference outputs included. However, explicitly documented constraint: batch size must be 1 (no batch processing support), single maintainer (sjmoran), no visible CI/test suite, and README explicitly requests users contact lead author for training difficulties. Verdict: publication-quality but engineering-constrained, not production-hardened.

Critical batch-size-of-1 limitation severely restricts deployment scalability—training and inference cannot parallelize across batches without architectural refactoring. Dependency stack is dated (torch==1.7.1, numpy==1.22.0 from 2021-2022 era) with no requirements pinning PyTorch minor versions, risking CUDA/cudnn compatibility issues. Single maintainer with no visible test suite or CI pipeline; contributing code changes is high-friction per README ('contact lead author').

No active development visible from file list metadata. Repository appears stable post-publication; contains example test outputs with reported PSNR/SSIM metrics embedded in filenames (e.g., 'a4576-DSC_0217_TEST_425_9_PSNR_34.596_SSIM_0.980.jpg'), suggesting inference pipeline is working. No open issues or PRs referenced in provided data.

git clone https://github.com/sjmoran/deeplpf-image-enhancement.git
cd deeplpf-image-enhancement
pip install -r requirements.txt  # installs torch==1.7.1, numpy==1.22.0, scikit-image, PIL, etc.
python main.py  # review main.py for required CLI args (not shown in snippet)

Daily commands: Exact commands inferred from main.py entry point existence and README reference to training/inference: python main.py with required arguments for dataset paths, model checkpoint, mode (train/test/inference). No explicit run scripts or Makefile visible; exact CLI signature not shown in provided snippets.

• main.py — Entry point for training and inference pipelines; orchestrates model training, validation, and testing workflows
• model.py — Core DeepLPF model architecture definition; implements the parametric filter generation network
• unet.py — UNet backbone encoder-decoder architecture used by DeepLPF for feature extraction and filter prediction
• data.py — Dataset loading and preprocessing for Adobe5K and other benchmark datasets; handles train/val/test splits
• util.py — Utility functions for image I/O, normalization, and tensor operations shared across the codebase
• metric.py — PSNR and SSIM evaluation metrics computation; critical for validating model performance
• requirements.txt — Python dependencies specification; essential for reproducible environment setup (PyTorch 1.7.1, numpy 1.22.0, etc.)

• UNet (unet.py) (PyTorch nn.Module) — Encodes input image to latent features via conv + maxpool; decodes to filter coefficient maps via upsampling + skip connections

Train DeepLPF on a new dataset

1. Create a new dataset class in data.py inheriting from torch.utils.data.Dataset with getitem returning (input_img, gt_img) pairs (data.py)
2. Add dataset split manifests (images_train.txt, images_valid.txt, images_test.txt) following Adobe5K convention (adobe5k_dpe/images_train.txt)
3. Update main.py argparse to accept --dataset_name and conditional dataset loading logic (main.py)
4. Run training with: python main.py --dataset_name <new_dataset> --model_dir <output_dir> --batch_size 1 (main.py)

Modify the UNet backbone or filter prediction head

1. Edit UNet architecture (layer depths, skip connections) in the UNet class definition (unet.py)
2. If changing output dimensions, update model.py DeepLPF.forward() to match expected filter coefficient dimensions (model.py)
3. Retrain from scratch with python main.py or resume from checkpoint with --resume_checkpoint_file (main.py)

Add a new image quality metric for evaluation

1. Implement metric computation function in metric.py (e.g., def compute_lpips(...) ) (metric.py)
2. Import and call the metric in main.py validation/test loops alongside PSNR/SSIM (main.py)
3. Log results to console and checkpoint filename for tracking (main.py)

Run inference on a single image

1. Load image and preprocess using util.py load_img and normalization utilities (util.py)
2. Initialize model from pretrained checkpoint and call model.inference() or forward() mode (model.py)
3. Denormalize output tensor and save with util.save_img, following Adobe5K example output naming (util.py)

• PyTorch 1.7.1 — Flexible tensor computation, autograd, and standard for deep learning research; enables parametric filter coefficient generation on GPU
• UNet architecture — Proven encoder-decoder for dense pixel-level prediction; extracts multi-scale features for local filter parameter generation
• PSNR/SSIM metrics — Standard image quality benchmarks for comparing enhancement results; scikit-image provides optimized implementations
• Local parametric filters (kernel-level) — Enables spatially-varying enhancement; avoids global learned LUT or global color correction limitations

• Batch size fixed at 1 during training

  • Why: Simplifies memory management and local parameter computation; matches CVPR 2020 reported results
  • Consequence: Slower per-epoch training; cannot leverage data parallelism across GPUs; users must retrain from scratch for custom datasets

• L1 pixel-level loss only (no perceptual loss)

  • Why: Simple, differentiable, and fast; standard for image-to-image tasks
  • Consequence: May produce blurrier results than perceptual losses; PSNR optimized but not necessarily visual quality

• Single pretrained checkpoint per task (DPE, UPE, DAR)

  • Why: Reduces model storage and simplifies inference; one model per application domain
  • Consequence: Cannot fine-tune or transfer learn easily between tasks; requires retraining for new enhancement types

• Inference on CPU or single GPU only

  • Why: Code designed for research reproducibility with modest hardware
  • Consequence: Not optimized for high-throughput production inference; batch inference requires manual refactoring

• Does not support batch size > 1 (explicitly stated in README)
• Does not include real-time or video enhancement pipelines
• Does not provide PyTorch quantization or ONNX export for mobile deployment
• Does not implement multi-task learning or dataset mixing strategies
• Does not include GUI or web server interface for end-users

Batch size limitation: code is hardcoded for batch_size=1—attempting higher batch sizes will fail silently or crash in unexpected ways (per README, no batch processing support yet). Dataset dependency: adobe5k_dpe/ folder must be present with correct directory structure and split files (images_train.txt, etc.) or data.py will fail. Torch version pinning: torch==1.7.1 is old; may fail on modern CUDA versions (e.g., CUDA 12.x)—requires CUDA 10.1-11.x. No explicit model weights URL: README implies pre-trained weights exist but no download link in file list; check for a 'pretrained_models/' directory or GitHub releases. Image format handling: code supports .tif and .png; ensure test images match one of these formats exactly.

• Local Parametric Filters — DeepLPF's core contribution—instead of predicting RGB outputs, it predicts spatially-varying filter parameters (curves, gains) that can be applied and interpreted as professional edits; understanding this abstraction is critical to modifying the model
• Image Enhancement / Computational Photography — This project sits in the low-level vision domain; knowing how exposure, color correction, and tone curves work in photography software is essential to understanding what the model is learning
• Encoder-Decoder Architecture (U-Net style) — DeepLPF likely uses an encoder-decoder CNN to progressively encode image features and decode per-pixel filter parameters; understanding this architecture pattern helps with modifying the model
• Perceptual Loss / Feature Reconstruction Loss — Enhancement models typically use perceptual loss (comparing deep features of output vs. ground truth) in addition to pixel-space MSE; metric.py implements pixel metrics, but training likely uses perceptual loss not shown
• Batch Normalization & Training Stability — The batch_size=1 constraint suggests batch norm may cause instability at higher batch sizes; understanding why batch norm differs at train vs. test time is critical for fixing the batch-size limitation
• Adobe5K Dataset / Deep Photo Enhancement — DeepLPF trains exclusively on Adobe5K (5000 images with professional Lightroom edits); knowing this dataset's structure and biases is essential for training, validation, and understanding model generalization
• PSNR and SSIM Metrics — model.py likely optimizes for PSNR/SSIM during training (via metric.py); understanding these metrics' limitations (PSNR assumes Gaussian noise, SSIM is structural but not perceptual) informs model debugging and result interpretation

• sjmoran/facets-net — By same author (sjmoran); related face image enhancement work using parametric filters, shares similar architectural philosophy
• chaofengc/Face-Restoration-Benchmark — Comprehensive evaluation framework for image restoration tasks; useful for benchmarking DeepLPF against other enhancement methods on Adobe5K
• aiff22/pytorch-image-quality-assessment — Standalone PyTorch PSNR/SSIM metric library; could replace metric.py with a more robust, tested implementation
• Jongchan/LPIPS — Learned Perceptual Image Patch Similarity—complementary loss metric for training image enhancement models; could improve training beyond pixel-space MSE
• NVlabs/unpaired-image-translation — Handles unpaired image enhancement (no paired training data); alternative approach to DeepLPF for scenarios where Adobe5K-style paired data unavailable

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 validation and multi-batch support to model.py and main.py

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 significant limitation. A contributor could add runtime validation in main.py to warn users, refactor the model.py architecture to handle variable batch dimensions, and add corresponding unit tests. This would unlock the codebase for practical production use.

• [ ] Review model.py to identify batch-size-dependent operations (likely in forward pass and parameter filter application)
• [ ] Refactor model.py to use batch-agnostic tensor operations (e.g., reshape logic that assumes batch=1)
• [ ] Update main.py to accept --batch_size argument and validate compatibility
• [ ] Add unit tests in a new tests/test_batch_sizes.py covering batch sizes of 1, 2, 4, 8
• [ ] Update README.md with new batch size capabilities and tested configurations

Create unit tests for data.py image loading and preprocessing pipeline

The data.py file handles critical image I/O and preprocessing but has no corresponding tests. Given the mixed file formats (PNG, TIF) in the dataset directories and the inconsistent naming conventions in adobe5k_dpe/ (some inputs paired with .tif, some with .png), there's risk of silent failures. Adding tests would ensure robust data loading.

• [ ] Create tests/test_data.py with unit tests for data.py functions
• [ ] Add tests for loading PNG and TIF formats from adobe5k_dpe/deeplpf_example_test_input/
• [ ] Test edge cases: mismatched file formats, missing paired files, corrupted images
• [ ] Verify preprocessing maintains numerical stability (check util.py normalization in conjunction)
• [ ] Add test that validates input/output image dimensions match expected sizes

Add GitHub Actions workflow for model inference testing and metric validation

The repo contains pre-trained models and test images but no CI pipeline to validate them. The metric.py file computes PSNR/SSIM (visible in output filenames like 'PSNR_27.426_SSIM_0.879.jpg'), but there's no automated testing. Adding a CI workflow would catch regressions when dependencies change and validate that pretrained models produce expected metric ranges.

• [ ] Create .github/workflows/test-inference.yml GitHub Actions workflow
• [ ] Configure workflow to run main.py inference on adobe5k_dpe/deeplpf_example_test_input/ images
• [ ] Use metric.py to compute PSNR/SSIM on outputs and compare against baseline ranges from adobe5k_dpe/deeplpf_example_test_inference/ results
• [ ] Add dependency pinning validation (numpy==1.22.0, torch==1.7.1, etc.) to catch compatibility breaks
• [ ] Fail the workflow if PSNR drops below 80% of baseline for any test image

• Add unit tests to metric.py for PSNR/SSIM computation—currently no test files visible; write tests in test_metric.py comparing against scikit-image.metrics implementations to catch numerical bugs
• Create a simple inference notebook (inference_example.ipynb) demonstrating end-to-end usage (load model, run on adobe5k_dpe/deeplpf_example_test_input/ images, visualize results) since README lacks code examples
• Extend batch_size support by refactoring main.py's training loop to handle batch_size > 1—this is explicitly flagged as blocking; start by identifying where batch_size=1 assumptions are hard-coded in data.py and model.py

• High · Outdated and Vulnerable Dependencies — requirements.txt. Multiple dependencies have known security vulnerabilities and are significantly outdated. numpy==1.22.0 (current: 1.26+), scipy==1.10.0 (current: 1.11+), torch==1.7.1 (current: 2.0+), and torchvision==0.8.2 (current: 0.16+) are several major versions behind. These versions contain known CVEs including arbitrary code execution vulnerabilities in numpy and scipy. Fix: Update all dependencies to their latest stable versions. At minimum: numpy>=1.24.0, scipy>=1.11.0, torch>=2.0.0, torchvision>=0.15.0. Run 'pip list --outdated' and 'pip-audit' to identify specific CVEs.
• High · Permissive Pillow Dependency Version — requirements.txt. pillow>=8.3.2 uses a minimum version constraint that is outdated. Pillow 8.3.2 was released in 2021 and contains multiple known CVEs including CVE-2021-28957 (buffer overflow) and other image processing vulnerabilities. Fix: Update to pillow>=10.0.0 or latest stable version. Change 'pillow>=8.3.2' to 'pillow>=10.1.0' or higher.
• Medium · Insecure Dependency: skimage Package — requirements.txt. The dependency 'skimage==0.0' is suspicious and likely a dummy/placeholder package. Version 0.0 does not exist in official PyPI repositories. This should be 'scikit-image' which is already listed separately, indicating potential confusion or typo that could lead to installing a malicious package. Fix: Remove 'skimage==0.0' from requirements.txt. Use 'scikit-image>=0.19.0' (already listed as scikit_image==0.18.1) and ensure consistency in naming.
• Medium · Outdated imageio Library — requirements.txt. imageio==2.9.0 is from 2021 and contains known vulnerabilities in image file handling. Current version is 2.33+. This library is used for image I/O and has had security patches for deserialization attacks. Fix: Update imageio to imageio>=2.31.0 to patch known security vulnerabilities in image file processing.
• Medium · Outdated matplotlib Dependency — requirements.txt. matplotlib==3.3.2 is from 2020 and predates several critical security updates. Current version is 3.8+. While matplotlib itself is less critical for security, it contains fixed vulnerabilities in data serialization. Fix: Update matplotlib to matplotlib>=3.7.0 or later.
• Low · No Dependency Pinning for torch and torchvision — requirements.txt. While dependencies use exact or minimum versions, there is no upper bound constraint on torch and torchvision. Major version changes could introduce breaking changes or incompatibilities. However, the specific versions are pinned which partially mitigates this. Fix: Consider using compatible release constraints: 'torch>=1.13.0,<3.0.0' and 'torchvision>=0.14.0,<1.0.0' to allow patch updates while preventing major breaking changes.
• Low · No Security Headers or Input Validation Visible — data.py, main.py (inferred). While this is a research code repository, there are no visible input validation mechanisms in the file structure for data processing. Image files from adobe5k_dpe and other sources are processed without apparent validation of file integrity or content. Fix: Implement file format validation and integrity checks before processing uploaded or external images. Verify image headers and dimensions before loading.
• Low · Absence of Security Documentation — Repository root. No security.md, SECURITY.md, or security policy is evident in the repository. For a published research project with pre-trained models, security guidelines are beneficial. Fix: Create a SECURITY.md file documenting security practices, how to report vulnerabilities, and recommended dependency updates.

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

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

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. 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.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sjmoran/deeplpf-image-enhancement shows verifiable citations alongside every claim.

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.

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 ≤ 661 days ago | Catches sudden abandonment since generation |

#!/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 "util.py" \\
  && ok "util.py" \\
  || miss "missing critical file: util.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 661 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~631d)"
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).

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