zhhoper · Abolmw4 · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026
diff --git a/.gitignore b/.gitignore
@@ -2,4 +2,10 @@
 *.sh
 log_test/
 result_1024
-
+env-dpr
+result/
+result*
+__pycache__
+.idea
+res.jpg
+.vscode
diff --git a/README.md b/README.md
@@ -19,17 +19,198 @@ Hao Zhou, Sunil Hadap, Kalyan Sunkavalli, David W. Jacobs. In ICCV, 2019
 <img src="result/light_06.png" width="120px" >
 </p>
 
-### Overview
- - Test script for 512x512 images: `testNetwork_demo_512.py`
- - Test script for 1024x1024 images: `testNetwork_demo_1024.py`
+---
+# Table of Contents
 
-### Dependencies ###
-<p> pytorch >= 1.0.0 </p>
-<p> opencv >= 4.0.0 </p>
-<P> shtools: https://shtools.oca.eu/shtools/ (optional)</p>
+- [Deep Single-Image Portrait Relighting](#deep-single-image-portrait-relighting)
+  - [Overview](#overview)
+  - [Notes](#notes)
+  - [Project Structure](#project-structure)
+  - [Requirements](#requirements)
+    - [Setup Instructions](#setup-instructions)
+  - [Brightness Configuration File](#brightness-configuration-file)
+  - [Running the Project](#running-the-project)
+  - [Data Preparation](#data-preparation)
+  - [Citation](#citation)
+---
+# Overview
+This project is an implementation of the paper "Deep Single-Image Portrait Relighting" presented at ICCV 2019. Its core goal is to perform relighting on single portrait images using deep learning: given an input portrait and a target lighting configuration, the model can re-render the same face under completely new illumination conditions. The method is fundamentally based on intrinsic image decomposition, where the network learns to separate an input image into its physically meaningful components—albedo (surface reflectance), geometry (represented by a depth map or surface normal vectors), and scene lighting. By disentangling these factors and then replacing the estimated lighting component with a desired target profile, the system renders the final output through a data-driven pipeline rooted in classic image formation models, enabling precise and controllable illumination effects.
+
+From a technical standpoint, the architecture relies on a U-Net with an Hourglass structure that preserves spatial resolution while extracting features. A key design choice is the use of second-order Spherical Harmonics (SH) for lighting representation, employing 9 coefficients: one for ambient light, three for directional lighting along the coordinate axes, and five for higher-frequency details such as soft shadows on curved facial surfaces. This compact yet physically grounded representation makes illumination manipulation both efficient and interpretable. The codebase supports processing images at 512×512 and 1024×1024 resolutions and depends on the shtools library for SH-related functions. It also provides utilities to convert between different SH coordinate conventions (e.g., bip2017, sfsNet) and the one adopted here. Training data is organized into separate train, validation, and test file lists, while the rendering-based data generation pipeline resides in a separate repository.
 
 ### Notes
-We include an example image and seven example lightings in data. Note that different methods may have different coordinate system for Spherical Harmonics (SH), you may need to change the coordiante system if you use SH lighting from other sources. The coordinate system of our method is in accordance with shtools, we provide a function utils_normal.py in utils to help you tansfer the coordinate system from [bip2017](https://gravis.dmi.unibas.ch/PMM/data/bip/) and [sfsNet](https://senguptaumd.github.io/SfSNet/) to our coordinate system. To use utils_normal.py you need to install shtools. The code is for research purpose only.
+
+- We provide one example input image and seven example lighting configurations in the `data` directory.
+
+- Different methods may adopt different coordinate systems for Spherical Harmonics (SH).  
+  If you use SH lighting from external sources, you may need to convert the coordinate system accordingly.
+
+- The coordinate system used in this project follows the convention of **shtools**.
+
+- We provide a utility script `utils_normal.py` (located in the `utils` directory) to help convert SH coefficients from:
+  - [bip2017](https://gravis.dmi.unibas.ch/PMM/data/bip/)
+  - [sfsNet](https://senguptaumd.github.io/SfSNet/)  
+  into the coordinate system used in this project.
+
+- To use `utils_normal.py`, you must install **shtools**.
+
+- This code is provided for **research purposes only**.
+
+---
+# Project Structure
+```text
+.
+├── candidiate_config
+│   ├── candidate1
+│   │   ├── rotate_light_04_0.txt
+│   │   ├── rotate_light_04.txt
+│   │   └── rotate_light_06.txt
+│   ├── candidate2
+│   │   ├── rotate_light_03_0.txt
+│   │   ├── rotate_light_03_1.txt
+│   │   ├── rotate_light_03.txt
+│   │   ├── rotate_light_04_0.txt
+│   │   └── rotate_light_04.txt
+│   └── candidate3
+│       ├── rotate_light_02.txt
+│       ├── rotate_light_03.txt
+│       ├── rotate_light_04_0.txt
+│       └── rotate_light_04.txt
+├── data
+│   ├── example_light
+│   │   ├── rotate_light_00.txt
+│   │   ├── rotate_light_01.txt
+│   │   ├── rotate_light_02.txt
+│   │   ├── rotate_light_03.txt
+│   │   ├── rotate_light_04.txt
+│   │   ├── rotate_light_05.txt
+│   │   └── rotate_light_06.txt
+│   ├── example_light_original
+│   │   ├── rotate_light_00.txt
+│   │   ├── rotate_light_01.txt
+│   │   ├── rotate_light_02.txt
+│   │   ├── rotate_light_03.txt
+│   │   ├── rotate_light_04.txt
+│   │   ├── rotate_light_05.txt
+│   │   └── rotate_light_06.txt
+│   ├── obama.jpg
+│   ├── test.lst
+│   ├── train.lst
+│   └── val.lst
+├── model
+│   ├── defineHourglass_1024_gray_skip_matchFeature.py
+│   └── defineHourglass_512_gray_skip.py
+├── obama.jpg
+├── README.md
+├── requirment.txt
+├── result
+│   ├── light_00.png
+│   ├── light_01.png
+│   ├── light_02.png
+│   ├── light_03.png
+│   ├── light_04.png
+│   ├── light_05.png
+│   ├── light_06.png
+│   ├── obama_00.jpg
+│   ├── obama_01.jpg
+│   ├── obama_02.jpg
+│   ├── obama_03.jpg
+│   ├── obama_04.jpg
+│   ├── obama_05.jpg
+│   └── obama_06.jpg
+├── test
+│   └── test_light_condition.py
+├── trained_model
+│   ├── trained_model_03.t7
+│   └── trained_model_1024_03.t7
+└── utils
+    ├── testNetwork_demo_1024.py
+    ├── testNetwork_demo_512.py
+    ├── utils_normal.py
+    ├── utils_SH.py
+    └── utils_shtools.py
+```
+
+# Requirements
+
+To run this project, please make sure the following prerequisites are met:
+
+- **Python 3.10**
+- All required packages listed in `requirement.txt`
+
+We strongly recommend using a virtual environment to avoid dependency conflicts.
+
+## Setup Instructions
+
+1. Create and activate a virtual environment:
+```bash
+python3.10 -m venv dpr-env
+source dpr-env/bin/activate      # On Linux / macOS
+# dpr-env\Scripts\activate       # On Windows
+```
+2. install python packages
+```bash
+pip install --upgrade pip
+pip install -r requirement.txt 
+```
+--- 
+
+# Brightness Configuration File
+
+- The directory `data/example_light_original` contains multiple lighting configuration files.  
+  Each configuration defines a specific lighting condition, including variations in illumination angle and light intensity.
+
+- These configuration files are used to simulate how the portrait appears under different lighting directions and strengths.
+
+- Detailed explanations of the configuration file parameters are provided in the following section.
+
+This configuration file contains settings that include 9 coefficients related to lighting.
+
+```text
+1.084125496282453138e+00
+-4.642676300617166185e-01
+2.837846795150648915e-02
+6.765292733937575687e-01
+-3.594067725393816914e-01
+4.790996460111427574e-02
+-2.280054643781863066e-01
+-8.125983081159608712e-02
+2.881082012687687932e-01
+```
+- The **first coefficient** represents the ambient light. This value determines the overall base brightness of the image regardless of direction.
+- The **next 3 coefficients** represent directional linear lighting along the x, y, and z axes respectively. These values specify the main light direction (left/right, up/down, front/back) shining onto the face.
+  - **Light along X axis**: Controls the directional    light intensity along the X axis (left ↔ right).
+  - **Light along Y axis**: Controls the directional light intensity along the Y axis (up ↔ down).
+  - **Light along Z axis**: Controls the directional light intensity along the Z axis (front ↔ back).
+
+- The **last 5 coefficients** represent complex lighting details used for more accurate simulation of light diffusion and softer shadows on curved surfaces (such as a human face).
+  - **Coefficient dependent on x·y**: Represents lighting variations influenced by the interaction between the X and Y axes.
+  - **Coefficient dependent on y·z**: Represents lighting variations influenced by the interaction between the Y and Z axes.
+  - **Coefficient dependent on 3z² − 1**: Controls spherical lighting deformation related to the Z‑axis curvature component.
+  - **Coefficient dependent on x·z**: Represents lighting variations influenced by the interaction between the X and Z axes.
+  - **Coefficient dependent on x² − y²**: Describes lighting differences caused by the relative contribution of the X and Y axes.
+
+These coefficients work together to create a realistic lighting effect in the rendered image.
+
+---
+# Running the Project
+
+- In the project repository, a set of **unit tests** has been provided that can be used to generate example outputs.
+
+- These tests are located in the corresponding test directory of the project.
+
+- The main methods for producing output are:
+  - `test_network_512_demo`
+  - `test_network_1024_demo`
+
+- These two methods demonstrate how to run the model and obtain relit portrait results.
+
+- The other test methods in the directory provide additional functionality and examples.  
+  You can understand their usage by reading the code.
+
+- For generating initial outputs and testing the pipeline, running the two demo methods above is sufficient.
+
+---
 
 ### Data Preparation
 We publish the code for data preparation, please find it in (https://github.com/zhhoper/RI_render_DPR).

diff --git a/candidiate_config/candidate1/rotate_light_04.txt b/candidiate_config/candidate1/rotate_light_04.txt
@@ -0,0 +1,9 @@
+0.27040471416103395
+-0.46426763006171867243
+-0.31910316690564172193
+-0.59721885776719108030
+-0.397097723888441
+-0.9453971324343751
+-0.47237695706463145
+0.024516914229173237
+-0.2663783549655807
diff --git a/candidiate_config/candidate1/rotate_light_04_0.txt b/candidiate_config/candidate1/rotate_light_04_0.txt
@@ -0,0 +1,9 @@
+0.7599764749674436
+-0.46426763006171867243
+-0.31910316690564172193
+-0.59721885776719108030
+0.5573975266935798
+0.5001595651885822
+0.7140101606482576
+0.380439487506566
+0.09412198842435937
diff --git a/candidiate_config/candidate1/rotate_light_06.txt b/candidiate_config/candidate1/rotate_light_06.txt
@@ -0,0 +1,9 @@
+0.6767738540804545
+-0.46426763006171695158
+-0.51123819939032077997
+0.44399628228860482659
+-0.8949978210034468
+-0.5563591448349721
+-0.04249981903504674
+-0.1447678371507346
+0.016304285486612224
diff --git a/candidiate_config/candidate2/rotate_light_03.txt b/candidiate_config/candidate2/rotate_light_03.txt
@@ -0,0 +1,9 @@
+0.13232263947052458
+-0.46426763006171867243
+0.26796693461949411263
+-0.62184476933764609718
+0.3971838831057054
+0.06932086334888465
+0.10502199133045376
+0.2126737014583967
+0.9105873950786283
diff --git a/candidiate_config/candidate2/rotate_light_03_0.txt b/candidiate_config/candidate2/rotate_light_03_0.txt
@@ -0,0 +1,9 @@
+0.08480793042881807
+-0.46426763006171867243
+0.26796693461949411263
+-0.62184476933764609718
+0.7620709851296886
+0.16208580389706828
+0.4707111097148129
+0.11499643536007365
+0.45468509701365134
diff --git a/candidiate_config/candidate2/rotate_light_03_1.txt b/candidiate_config/candidate2/rotate_light_03_1.txt
@@ -0,0 +1,9 @@
+0.1962672986198406
+-0.46426763006171867243
+0.26796693461949411263
+-0.62184476933764609718
+0.9644050707577712
+0.5356968951299693
+0.30490039971179483
+0.4148029522455058
+0.9945177431726548
diff --git a/candidiate_config/candidate2/rotate_light_04.txt b/candidiate_config/candidate2/rotate_light_04.txt
@@ -0,0 +1,9 @@
+0.13644282027529087
+-0.46426763006171867243
+-0.31910316690564172193
+-0.59721885776719108030
+0.5937625728758151
+0.2537910536841331
+0.09708440767577975
+0.6908752097806585
+0.9128589362594567
diff --git a/candidiate_config/candidate2/rotate_light_04_0.txt b/candidiate_config/candidate2/rotate_light_04_0.txt
@@ -0,0 +1,9 @@
+0.04725591345770108
+-0.46426763006171867243
+-0.31910316690564172193
+-0.59721885776719108030
+0.32721833828615376
+0.2651040031674805
+0.16997635830083313
+0.8322291732242509
+0.6038195991231404
diff --git a/candidiate_config/candidate3/rotate_light_02.txt b/candidiate_config/candidate3/rotate_light_02.txt
@@ -0,0 +1,9 @@
+-0.06418672177194007
+-0.46426763006171795078
+0.65325246884684284865
+-0.17820888627524578141
+0.5232245651178373
+0.403902811802879
+0.44893903369868327
+0.8274382240234986
+0.765513739352323
diff --git a/candidiate_config/candidate3/rotate_light_03.txt b/candidiate_config/candidate3/rotate_light_03.txt
@@ -0,0 +1,9 @@
+-0.44333633966552344
+-0.46426763006171867243
+0.26796693461949411263
+-0.62184476933764609718
+0.6470974817487151
+0.06988406362642641
+0.826308199976985
+0.5886195484274779
+0.49124674739238094
diff --git a/candidiate_config/candidate3/rotate_light_04.txt b/candidiate_config/candidate3/rotate_light_04.txt
@@ -0,0 +1,9 @@
+0.6225771867250876
+-0.46426763006171867243
+-0.31910316690564172193
+-0.59721885776719108030
+0.611293056201971
+0.13495867234579872
+0.7831822217344969
+0.9466877512278259
+0.7823907396310225
diff --git a/candidiate_config/candidate3/rotate_light_04_0.txt b/candidiate_config/candidate3/rotate_light_04_0.txt
@@ -0,0 +1,9 @@
+0.3395404471917278
+-0.46426763006171867243
+-0.31910316690564172193
+-0.59721885776719108030
+0.22729003974963624
+0.9256625956590697
+0.9071189187796489
+0.34868353659096296
+0.10067127449200142
diff --git a/data/example_light/rotate_light_00.txt b/data/example_light/rotate_light_00.txt
@@ -6,4 +6,4 @@
 4.790996460111427574e-02
 -2.280054643781863066e-01
 -8.125983081159608712e-02
-2.881082012687687932e-01
+2.881082012687687932e-01
diff --git a/data/example_light/rotate_light_01.txt b/data/example_light/rotate_light_01.txt
@@ -1,9 +1,9 @@
-1.084125496282453138e+00
+0.000000000000000000e+00
 -4.642676300617170626e-01
 5.466255701105990905e-01
 3.996219229512094628e-01
--2.615439760463462715e-01
--2.511241554473071513e-01
-6.495694866016435420e-02
-3.510322039081858470e-01
-1.189662732386344152e-01
+0.000000000000000000e+00
+0.000000000000000000e+00
+0.000000000000000000e+00
+0.000000000000000000e+00
+0.000000000000000000e+00
diff --git a/data/example_light/rotate_light_02.txt b/data/example_light/rotate_light_02.txt
@@ -1,9 +1,9 @@
-1.084125496282453138e+00
+0.000000000000000000e+00
 -4.642676300617179508e-01
 6.532524688468428486e-01
 -1.782088862752457814e-01
-3.326676893441832261e-02
--3.610566644446819295e-01
-3.647561777790956361e-01
--7.496419691318900735e-02
--5.412289239602386531e-02
+0.000000000000000000e+00
+0.000000000000000000e+00
+0.000000000000000000e+00
+0.000000000000000000e+00
+0.000000000000000000e+00