Onboarding: sjmoran/low-light-video-enhancement

Generated by RepoPilot · 2026-05-06 · 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. 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/low-light-video-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.

Verdict

WAIT — Stale — last commit 5y ago

• 2 active contributors
• Other licensed
• ⚠ Stale — last commit 5y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ 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/low-light-video-enhancement repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sjmoran/low-light-video-enhancement.

What it runs against: a local clone of sjmoran/low-light-video-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/low-light-video-enhancement | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 1695 days ago | Catches sudden abandonment since generation |

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

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sjmoran/low-light-video-enhancement. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sjmoran/low-light-video-enhancement.git
#   cd low-light-video-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/low-light-video-enhancement and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1695 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1665d)"
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/low-light-video-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>

TL;DR

SIDGAN is a CycleGAN-based video enhancement system that brightens low-light videos by learning mappings through intermediate synthetic domains. It uses a two-stage approach: mapping normal-light videos (Vimeo, domain A) → long-exposure synthetic data (SID Motion domain B) → short-exposure real low-light video (domain C), enabling training without paired low-light/normal-light video datasets. Organized as a training pipeline: src/CycleGAN.py contains the core generator/discriminator architecture, utilities/ holds data loaders and image pooling, models/ICCV_architectures.py and models/unet.py define encoder-decoder backbones, and two top-level training scripts (train_cyclegan_a2b.py, train_cyclegan_b2c.py) execute the two-stage domain mapping.

Who it's for

Computer vision researchers and video processing engineers working on low-light enhancement who need to avoid paired training data collection; specifically those implementing or extending the ECCV 2020 SIDGAN paper or building domain-adaptation video pipelines.

Maturity & risk

Actively maintained research code (ECCV 2020, recent README updates). Author's personal repository with link to official Huawei Noah implementation. Dependencies pinned to specific versions (TensorFlow 1.15.0, Keras 2.3.1). No visible CI/test suite in file structure suggests research-quality rather than production-grade code.

Critical dependency risk: TensorFlow 1.15.0 and Keras 2.3.1 are deprecated (released 2019-2020, security unsupported since ~2021); migration to TF 2.x will require substantial refactoring. Single-maintainer repository with sparse open issue data. No test coverage visible in file list. Python 3.5 requirement in README is extremely outdated.

Active areas of work

No active development visible in provided file structure; this is a stable research artifact. The README notes the official maintained version is at huawei-noah/noah-research/SIDGAN, suggesting this personal repo is documentation/reference rather than the active development location.

Get running

git clone https://github.com/sjmoran/low-light-video-enhancement.git
cd low-light-video-enhancement
conda create -n sidganenv python=3.5
conda activate sidganenv
pip install -r requirements.txt
# Download SID Motion and Vimeo-90k datasets, structure as shown in README
python train_cyclegan_a2b.py --data_root $PATH_TO_DATA --project_root $(pwd) --name my_experiment

Daily commands: Stage 1 (normal → long-exposure mapping): python train_cyclegan_a2b.py --data_root $PATH_TO_DATA --project_root $PATH_TO_CODE --name experiment_a2b. Stage 2 (long → short-exposure mapping): python train_cyclegan_b2c.py --data_root $PATH_TO_DATA --project_root $PATH_TO_CODE --name experiment_b2c. Outputs saved to experiments/$EXP_NAME/saved_models/.

Map of the codebase

• src/CycleGAN.py: Core CycleGAN model with generator and discriminator forward passes, cycle consistency loss, and identity loss computation
• train_cyclegan_a2b.py: Entry point for stage 1 training (Vimeo→SID long-exposure); defines argument parsing, data loading, training loop, and checkpoint saving
• train_cyclegan_b2c.py: Entry point for stage 2 training (SID long→short-exposure); completes the two-stage domain mapping pipeline
• models/unet.py: U-Net generator backbone with skip connections; critical for preserving spatial details during low-light enhancement
• utilities/data_loader.py: Handles SID Motion and Vimeo-90k dataset loading and preprocessing; any custom dataset integration starts here
• utilities/image_pool.py: Implements CycleGAN replay buffer to stabilize discriminator training by storing historical generated images

How to make changes

Start with src/CycleGAN.py to adjust generator/discriminator architecture; modify utilities/data_loader.py to support new dataset formats (currently expects SID Motion and Vimeo-90k structure); edit models/unet.py to change encoder-decoder depth; tweak loss weights in train_cyclegan_a2b.py and train_cyclegan_b2c.py for domain adaptation sensitivity.

Traps & gotchas

1. Dataset structure is strict: expects SID_long, VBM4D_rawRGB, and vimeo folders in data/ root; no fallback or defaults. 2. TensorFlow 1.x session management: code likely uses tf.Session() explicitly; won't run on TF 2.x without substantial refactoring. 3. GPU memory: CycleGAN training requires high VRAM; no gradient accumulation or mixed precision visible. 4. Python 3.5 requirement in README is outdated; actual compatibility with modern Python untested.

Concepts to learn

• CycleGAN (Cycle-Consistent Generative Adversarial Networks) — Core algorithm enabling unpaired domain translation (Vimeo→SID→real low-light) without aligned low-light/normal-light training pairs, solving the data collection bottleneck
• Intermediate Domain Mapping — Two-stage A→B→C pipeline (normal→synthetic long-exposure→real short-exposure) improves domain gap handling vs direct A→C translation, central to SIDGAN's contribution
• Instance Normalization — Normalizes per-image statistics in generator; contrasts with batch norm and enables style transfer invariance, critical for cross-domain video consistency
• Image Replay Buffer (History Buffer) — utilities/image_pool.py stores historical generated images to stabilize discriminator training in GANs; prevents mode collapse in unpaired domain adaptation
• Cycle Consistency Loss — Enforces that x→y→x reconstruction equals x (and vice versa); enables unpaired training by replacing paired supervision, core to CycleGAN architecture
• U-Net Encoder-Decoder with Skip Connections — Generator backbone (models/unet.py) preserves spatial detail during enhancement via concatenated skip connections; essential for fine-grained video quality
• Identity Loss — Regularizes generator to preserve inputs already in target domain (e.g., images that look normal-lit should stay unchanged); reduces over-translation artifacts

Related repos

• junyanz/CycleGAN — Original CycleGAN PyTorch implementation; provides reference architecture and training patterns adapted here to TensorFlow for video enhancement
• huawei-noah/noah-research — Official Huawei maintenance of SIDGAN; this repo's data and models likely sync from here; go there for production-grade code
• cchen156/Seeing-Motion-in-the-Dark — SID Motion dataset source referenced in README; provides the paired low/long-exposure video data used for domain B training
• PhilippeIsaacson/RefEnh — Complementary low-light enhancement work; uses similar CycleGAN approach for image rather than video domain adaptation
• chaofengc/Face-Restoration-Benchmark — Related domain adaptation use of CycleGAN for quality improvement; shares architectural patterns and image pool stabilization techniques

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 inference pipeline with pre-trained model loading

The repo mentions 'pre-trained models' in the README but there's no clear inference script or model loading utility. Contributors could create a dedicated inference module that loads pre-trained weights and processes video/image inputs, making the repo immediately usable for end-users.

• [ ] Create src/inference.py with model loading from pre-trained weights
• [ ] Add model weight download/path configuration in utilities/
• [ ] Create example inference script (e.g., run_inference.py) demonstrating A→B→C domain mapping
• [ ] Add error handling for missing model files with helpful download instructions

Create data loader tests and validation utilities

utilities/data_loader.py exists but there are no visible unit tests. This is critical for a research repo processing video frames - tests would catch data pipeline issues early and help contributors understand expected input formats.

• [ ] Create tests/test_data_loader.py with fixtures for sample video frames
• [ ] Add validation in utilities/data_loader.py to check frame dimensions, color spaces, and batch shapes
• [ ] Create utilities/data_validation.py with functions to verify dataset structure (matching train_cyclegan_a2b.py and train_cyclegan_b2c.py requirements)
• [ ] Add example dataset directory structure documentation in README

Add dependency pinning and environment setup script

The requirements.txt pins old versions (TensorFlow 1.15.0, Keras 2.3.1) which are EOL and may fail on modern systems. A contributor could create install scripts and updated compatibility notes for users trying to run this on current hardware/OS combinations.

• [ ] Create setup.sh and setup.bat scripts to handle environment creation
• [ ] Add requirements-dev.txt for development dependencies (pytest, flake8, etc.)
• [ ] Document TensorFlow 1.x → 2.x migration notes or CPU-only fallback in README
• [ ] Add GPU/CPU detection logic in src/train_cycleGAN.py with fallback warnings

Good first issues

• Add unit tests for utilities/image_pool.py replay buffer logic (no test coverage visible); validate FIFO behavior and tensor shape handling with mock image batches
• Document the expected dimensions and color space (RGB vs BGR) for SID Motion and Vimeo-90k data in utilities/data_loader.py; currently unclear from inline comments
• Create a lightweight inference script (currently missing) that loads a trained model checkpoint from experiments/$EXP_NAME/saved_models/ and brightens a single low-light video frame for end-user validation

Top contributors

• @sjmoran — 29 commits
• @Ubuntu — 1 commits

Recent commits

• 169bd69 — Create requirements.txt (sjmoran)
• 413f331 — Update README.md (sjmoran)
• 3be3bbe — Update README.md (sjmoran)
• 3c0a248 — Update README.md (sjmoran)
• 5afddf8 — Update README.md (sjmoran)
• f00ebd7 — Update README.md (sjmoran)
• 3fbee92 — Update README.md (sjmoran)
• cca6065 — Update README.md (sjmoran)
• 4e0eca2 — Update README.md (sjmoran)
• 05d68d5 — Update README.md (sjmoran)

Security observations

• High · Outdated TensorFlow GPU with Known Vulnerabilities — requirements.txt - tensorflow_gpu==1.15.0. TensorFlow GPU 1.15.0 is significantly outdated (released 2019) and contains multiple known security vulnerabilities including arbitrary code execution and denial of service issues. TensorFlow 1.15.x reached end-of-life in 2020. Fix: Upgrade to TensorFlow 2.x (latest stable version, e.g., 2.13+) or at minimum TensorFlow 2.10+. Review compatibility with Keras 2.3.1 as TensorFlow 2.x has integrated Keras.
• High · Outdated Keras with Known Vulnerabilities — requirements.txt - Keras==2.3.1. Keras 2.3.1 is outdated and was released in 2019. It is now integrated into TensorFlow and no longer maintained as a standalone package. Multiple security issues may exist in this legacy version. Fix: Remove Keras as a standalone dependency and use the integrated keras module from TensorFlow 2.x. Update to TensorFlow >= 2.10 which includes up-to-date Keras.
• High · Vulnerable Pillow Version — requirements.txt - Pillow==8.1.2. Pillow 8.1.2 (released early 2021) contains multiple known vulnerabilities including CVE-2021-25292, CVE-2021-25293, and others related to image processing that could lead to denial of service or arbitrary code execution. Fix: Upgrade Pillow to version 9.5.0 or later (preferably latest stable, e.g., 10.x). These versions address critical image parsing vulnerabilities.
• High · Vulnerable OpenCV Version — requirements.txt - opencv_python==4.4.0.42. OpenCV 4.4.0.42 contains known vulnerabilities including denial of service issues in video processing functionality. The package is significantly outdated. Fix: Upgrade to OpenCV 4.8.0 or later. Review the OpenCV security advisories for patches related to video decoding.
• Medium · Outdated NumPy with Potential Issues — requirements.txt - numpy==1.18.5. NumPy 1.18.5 is outdated (released 2020). While primarily a numerical library, outdated versions may have unpatched vulnerabilities in array processing that could be exploited through malicious input data. Fix: Upgrade to NumPy 1.24.x or later (1.24.x for Python 3.9+, or newer versions for Python 3.10+). Ensure compatibility with TensorFlow after upgrade.
• Medium · Outdated SciPy Version — requirements.txt - scipy==1.2.0. SciPy 1.2.0 is significantly outdated (released 2019) and may contain unpatched vulnerabilities in numerical computation and image processing functions. Fix: Upgrade to SciPy 1.11.0 or later. Verify compatibility with upgraded NumPy and TensorFlow versions.
• Medium · Missing Dependency Pinning Strategy — requirements.txt. The requirements.txt file uses exact version pinning without considering security updates. There is no mechanism for automated security updates or vulnerability scanning mentioned in the repository. Fix: Implement a security update strategy: (1) Use tools like Dependabot or Snyk to monitor dependencies; (2) Establish a schedule for periodic security updates; (3) Consider using compatible release clauses (e.g., ~=1.15) for non-critical components while pinning critical ones.
• Low · No Security Configuration Files — Repository root. The repository lacks security configuration files such as SECURITY.md, .gitignore with sensitive patterns, or security policy documentation. This makes it harder for security researchers to report vulnerabilities responsibly. Fix: Add a SECURITY.md file with vulnerability reporting guidelines. Add a comprehensive .gitignore to prevent accidental commits of credentials, models, or sensitive data.
• Low · Missing — undefined. undefined Fix: undefined

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.