LibLLIE

A unified Python toolkit for low-light image enhancement.

English Docs | 中文文档 | CLI | Configuration

LibLLIE is an open-source library for low-light image enhancement (LLIE). It brings traditional enhancement algorithms, deep-learning models, training, prediction, image I/O, and evaluation into one consistent interface.

The library is built for research and experimentation: you can quickly compare classical methods, run or train neural models, evaluate enhanced images, and extend the framework with your own models, losses, datasets, algorithms, or metrics.

Highlights

• Unified top-level API: predict, train, evaluate, imread, imwrite, list.
• Training pipeline with YAML configuration, checkpoints, validation, and resumable experiments.
• Evaluation utilities for full-reference and no-reference image quality metrics such as PSNR, SSIM, MSE, MAE, LPIPS, LOE, NIQE, MUSIQ, and PI.
• Automatic component registration for custom extensions.

Documentation

See below for a compact quick start. For complete guidance, use the full docs:

Topic	English	中文
API overview	docs/guide/overview.md	docs-zh-CN/guide/overview.md
Image I/O	docs/guide/image_io.md	docs-zh-CN/guide/image_io.md
Prediction	docs/guide/predict.md	docs-zh-CN/guide/predict.md
Training	docs/guide/train.md	docs-zh-CN/guide/train.md
Evaluation	docs/guide/evaluate.md	docs-zh-CN/guide/evaluate.md
CLI	docs/usage/cli.md	docs-zh-CN/usage/cli.md
Configuration	docs/usage/cfg.md	docs-zh-CN/usage/cfg.md

Install

LibLLIE requires Python>=3.8 and PyTorch>=2.0.

Clone the repository, then install from source when developing or using the latest GitHub version:

cd LibLLIE
pip install -e .

also, you can install it as a regular package: (Not yet implemented.)

pip install libllie

Install skill

Before installing the skill, complete the Install steps above so the LibLLIE package and its Python dependencies are available in your environment.

Then install the skill with the Makefile from the repository root:

make link-skills
# using uv
make link-skills env=uv
# using conda (should specify env name)
make link-skills env=conda name=<env-name>

By default, this registers the plain python command.

This step links the skill in the agents' global environment and writes the LibLLIE codebase path and Python command to $HOME/.agents/env/libllie-cli.env unless that file already defines both LIBLLIE_ROOT and LIBLLIE_PYTHON.

To remove or refresh the global skill link without changing the environment:

make unlink-skills
make relink-skills

To clear the registered environment:

make clean-skill-env

Quick Start

### CLI

You can use either libllie or llie as the command.

# List registered models, algorithms, metrics, losses, and datasets
libllie list 
# or 
llie list

# Enhance one image with a traditional method
libllie predict he input.jpg -o results/he_output.png
# or
llie predict he input.jpg -o results/he_output.png

# Evaluate enhanced images
libllie evaluate --en-img-dir path/to/enhanced/images/dir --ref-img-dir path/to/reference/images/dir --metrics PSNR SSIM
# or
llie eval --en path/to/enhanced/images/dir --ref path/to/reference/images/dir --metrics PSNR SSIM

Python

For traditional algorithms, you only need to provide the algorithm name and the low-light-enhanced image to be enhanced.

import libllie as llie

enhanced, saved_path = llie.predict(
    "he",
    "input.jpg",  # low-light-image
    output="results/he_output.png",
)

For deep-learning inference, pass a trained checkpoint path:

enhanced, saved_path = llie.predict(
    "path/to/llie.pt",
    "input.jpg",
    output="results/zerodce_output.png",
    device="cuda",
)

Supported Components

Deep-Learning Models

Model	Year	Venue	Paper	Official GitHub	Upstream license
LLNet	2017	Pattern Recognition	paper	code	-
KinD	2019	ACM MM	paper	code	-
Zero-DCE	2020	CVPR	paper	code	CC BY-NC 4.0
Zero-DCE++	2021	IEEE TPAMI	paper	code	CC BY-NC 4.0
RUAS	2021	CVPR	paper	code	-
KinD++	2021	IJCV	paper	code	-
EnlightenGAN	2021	IEEE TIP	paper	code	-
SCI	2022	CVPR	paper	code	-
URetinex-Net	2022	CVPR	paper	code	MIT
LEDNet	2022	ECCV	paper	code	S-Lab License 1.0
LLFlow	2022	AAAI	paper	code	CC BY-NC-SA 4.0
RetinexFormer	2023	ICCV	paper	code	-
PairLIE	2023	CVPR	paper	code	-
LLFormer	2023	AAAI (Oral)	paper	code	CC BY-NC-SA 4.0
Zero-IG	2024	CVPR	paper	code	-
DarkIR	2025	CVPR	paper	code	MIT
HVI-CIDNet	2025	CVPR	paper	code	MIT

The license column reports the license explicitly stated by each upstream repository. A - means that no explicit upstream license was found; a public repository without a license does not by itself grant reuse rights. Some listed licenses restrict commercial use and are therefore not OSI-approved open-source licenses.

Traditional Algorithms

Algorithm	Documentation	Official GitHub	Upstream license
Gamma	docs/algorithms/gamma.md	-	-
Log	docs/algorithms/log.md	-	-
HE	docs/algorithms/he.md	-	-
AHE	docs/algorithms/ahe.md	-	-
CLAHE	docs/algorithms/clahe.md	-	-
RCLAHE	docs/algorithms/rclahe.md	-	-
Retinex	docs/algorithms/retinex.md	-	-
DCP	docs/algorithms/dcp.md	-	-
NPE	docs/algorithms/npe.md	-	-
LIME	docs/algorithms/lime.md	-	-
BIMEF	docs/algorithms/bimef.md	-	-
GCP	docs/algorithms/gcp.md	code	-

Evaluation Metrics

Type	Metrics
Full-reference	PSNR, SSIM, MSE, MAE, LPIPS, LOE
No-reference	NIQE, MUSIQ, PI

See docs/guide/evaluate.md and docs/custom/metric.md for usage and extension details.

Training

LibLLIE provides a unified trainer for registered models and datasets. You can train through keyword arguments:

import libllie as llie

llie.train(
    model="ZeroDCE",
    dataset="CommonDataset",
    root_dir="datasets/LOL",
    loss="zerodce",
    epochs=10,
    batch_size=4,
    device="cuda",
)

Or train from YAML:

llie.train("libllie/deepLearning/config/ZeroDCE.yaml")

You can also train from the command line. Both llie and libllie are supported as command names:

# Train from YAML after setting data.root_dir in the configuration file
llie train libllie/deepLearning/config/ZeroDCE.yaml

# Override YAML settings from the command line
llie train libllie/deepLearning/config/ZeroDCE.yaml --kwargs root_dir=datasets/LOL epochs=10 batch_size=4 device=cuda

# Train entirely from command-line arguments
llie train --kwargs model=ZeroDCE root_dir=datasets/LOL epochs=10 batch_size=4 device=cuda

# Resume training from a checkpoint
llie train libllie/deepLearning/config/ZeroDCE.yaml --kwargs root_dir=datasets/LOL resume=checkpoints/ZeroDCE_LOLv1Dataset/checkpoints/last.pt

Training outputs are saved under checkpoints/{Model}_{Dataset} by default, including checkpoints, logs, and the resolved training configuration.

Extension System

LibLLIE uses automatic registration for major components. After a custom component is imported, it can be listed and used through the same top-level API.

Component	Base class	Guide
Deep-learning model	LLIEModel	custom model
Training loss	BaseLoss	custom loss
Dataset	BaseDataset	custom dataset
Traditional algorithm	LLIEnhancer	custom algorithm
Evaluation metric	BaseMetric	custom metric

Project Layout

libllie/
  data/            Image I/O, transforms, datasets
  traditional/     Traditional LLIE algorithms
  deepLearning/    Models, losses, trainer, predictor, YAML configs
  evaluation/      Evaluator and image quality metrics
docs/              English documentation
docs-zh-CN/        Chinese documentation
examples/          Runnable examples
test/              Test suite

Testing

Run the test suite:

python -m pytest -q test

Contributing

Contributions are welcome. Good first contributions include:

• adding or improving algorithm documentation,
• adding examples for existing models,
• implementing new LLIE algorithms or metrics,
• improving tests for training, prediction, and evaluation workflows.

Please keep new components consistent with the existing registration system and add focused tests when behavior changes.

License

LibLLIE is released under the MIT License. See LICENSE.

Contact

Glory Wan
glory947446@gmail.com

Bibtex

coming soon