DazhLight 1.0.0 — manual

DazhLight evens out frame-to-frame exposure and colour-balance flicker in one stop-motion shot. You mark parts of the set that never move, mark the frames where you changed the lights on purpose, review the result as a flip-book and graph, and export corrected frames with a report. It runs in your browser from a single file and makes no network requests.

Tested environment: Google Chrome 152 on Ubuntu Linux 22.04 (desktop window and a 390 px narrow window). Other browsers, Windows and macOS have not been tested. The example shot is an original synthetic test shot made by a script; it is not a photographed production and the results below are not a promise for every real shot.

1. Before you start

Unzip DazhLight-1.0.0.zip to a folder of your choice.
Open DazhLight.html in Google Chrome (double-click it, or drag it onto a Chrome window). No installation, account or internet connection is needed.
Have one shot as a folder of numbered PNG or JPEG frames (for example take3_0001.jpg … take3_0240.jpg).

DazhLight start screen with the five steps on the left and the empty viewer — Start screen. The five steps are on the left; the viewer and the brightness graph are in the middle.

2. First result with the example (about two minutes)

In step 1, press Choose frame files, open the folder example/lamp-cue-shot, select all 48 frames (Ctrl+A) and confirm. DazhLight reports 48 frames ready · 640×360 px · PNG.
Press Load settings… and choose example/lamp-cue-shot.dazhlight.json. It sets reference boxes A and B, check box C, a cue at frame 25, the colour-balance mode and box B ignored on frames 30–32, then measures all frames. If you choose the settings while the frames are still being checked, DazhLight says so under the button and applies them as soon as the check has finished.
Open 4 Review, then 5 Export and press Export ZIP. Chrome saves lamp-dazhlight.zip to your downloads folder.

Step 2 with boxes A and B on the wall, check box C, and the brightness graph — Step 2: reference boxes A and B on static parts of the wall and a check box C that is measured but never used for correction.

Expected result

Measured on check box C (independent ImageMagick measurement)	Before	After
Frame-to-frame variation inside each lighting segment (coefficient of variation)	4.4% and 4.5%	0.13% and 0.24%
Brightness step at the lamp cue (segment 2 ÷ segment 1)	1.251 (median of source frames)	1.244 — the step is kept
Blue-channel wobble (blue ÷ luminance variation)	1.2%	at most 0.29% in any channel
Gains in `gains.csv` compared with gains computed independently from the source frames	within 0.32% on every frame

The graph shows the same thing: the grey line (original) jumps from frame to frame, the blue line (corrected) is flat inside each segment and keeps the step at the orange cue line.

3. Your own frames

Choose frame files (select every frame of one shot) or Choose a folder, or drop the frames on the dashed area. Files that are not PNG or JPEG (for example .CR2 raw files or notes) are listed as ignored.
Frames are ordered by the number at the end of the name, so f9 comes before f10. If numbers are missing (a gap), DazhLight lists them and asks you to confirm before you continue. Missing frames are not created.
If something blocks the shot, the message names the file and the reason, and nothing is changed.

4. Supported frames and limits

Accepted	Opaque 8-bit RGB PNG (also RGBA when every pixel is fully opaque) and 8-bit RGB JPEG (baseline or progressive). Untagged frames and PNG frames with an sRGB declaration are treated as sRGB.
Refused with a message	16-bit, indexed, greyscale, animated or transparent PNG (including a `tRNS` transparency chunk); PNG gamma/colour chunks (`gAMA`, `cHRM`) without an sRGB declaration; any PNG `cICP` colour-space declaration or HDR metadata (`mDCV`, `cLLI`), even next to an sRGB declaration, because `cICP` takes precedence over it; any embedded ICC colour profile (PNG or JPEG); CMYK, greyscale or 12-bit JPEG; lossless/arithmetic JPEG; EXIF orientation other than 1 (JPEG or PNG); damaged, truncated or undecodable files; files whose content does not match their extension.
Shot	2–300 frames; all frames the same size; longest side 32–1920 px; at most 8 MiB per file and 256 MiB in total; at most 120 million pixels in total (for example 57 frames of 1920×1080).
Names	Each name needs a frame number; one naming pattern per shot; two files with the same number (such as `f_01` and `f_1`) block the shot.
Output	One ZIP. Corrected frames are new lossless 8-bit PNG files without metadata (EXIF is not copied). Frames you leave unchanged are copied byte for byte in their original format. The ZIP is about the size of the corrected frames as PNG: about 335 MiB for a very noisy shot near the pixel limit (see below), much less for ordinary frames. A 512 MiB safety stop ends any export that would grow larger before anything is downloaded, without touching your frames. Ordinary shots stay well below it; unusual mixes within the limits above can reach it, for example many large frames left unchanged together with very noisy corrected frames.

Camera JPEGs that carry an embedded colour profile are refused in this version. Re-save them as sRGB without an embedded profile in your photo editor before opening them.

How the limits were checked

Each limit was tried on both sides in the tested Chrome, with original test frames made by a script. The accepted full-size shots were measured and exported, the ZIPs were checked with separate tools (CRC, SHA-256 of every source and output, ImageMagick), and the source files were hashed before and after to confirm they did not change.

Limit	Accepted	Refused with a message
Frames per shot	2 and 300	1 (“At least 2 frames”) and 301 (“the limit is 300”)
Longest side	1920 px (landscape and portrait)	1921 px (“at most 1920 px”)
Shortest side	32 px	31 px (“smaller than 32 px”)
File size	exactly 8 MiB	8 MiB + 1 byte (“larger than 8 MiB”)
Shot size	32 frames of exactly 8 MiB (256 MiB), 1920×1080: exported in about 21 s, ZIP 188 MiB	33 such frames, 264 MiB (“the limit is 256 MiB”)
Pixels per shot	300 frames of 800×500 = exactly 120,000,000 pixels: exported in about 14 s	300 frames of 800×501 (“120 million pixels”)
Largest export	57 frames of 1920×1080 random noise (118 million pixels, 166 MiB of JPEG) exported in about 39 s to a 335 MiB ZIP; noise does not compress, so ordinary frames give smaller ZIPs

Times are from one Linux desktop (16 cores, 32 GB memory) and only show the order of magnitude; a slower computer takes longer. Large exports hold the whole ZIP in memory until Chrome saves it, so close other heavy tabs first.

5. Reference and check boxes

In step 2, drag on the picture to draw a box; drag inside a box to move it. Every box also has number fields (left, top, width, height in pixels) for exact keyboard editing.
Put one to three reference boxes on parts of the set that never move and are lit like the rest of the scene: wall, floor, backdrop. Avoid areas the puppet, rigs, hands or shadows will cross, very dark areas and pure white areas. Boxes need at least 16×16 px.
A check box is measured but not used for correction. The graph shows it, so you can see an independent before/after.
Choose Brightness only (one gain per frame, the default) or Brightness and colour balance (separate red, green and blue gains, for white-balance flicker).
Press Measure frames. Moving or resizing a box clears the measurement until you measure again.

Each frame's gain is the segment's median reference level divided by the frame's level, measured in linear light with the brightest and darkest 10% of box pixels trimmed. Gains are limited to 0.5–2.0; a limited frame is marked and never reported as matched.

6. Cues and exclusions

Step 3 on frame 30 with box B drawn dashed and marked ignored, and tables of cues and exclusions — Step 3 on frame 30: the puppet lifts a card into box B, so box B is ignored on frames 30–32 and those frames are corrected from box A alone.

Step through frames with ← → (or the slider). On the first frame after an intentional lighting change, press C (or Cue on frame …). Each cue starts a new segment that keeps its own brightness.
If something covers a reference box on a frame, press 1–4 (or Ignore box …) to ignore that box on that frame. Ignored samples are left out of both the segment target and that frame's gain.
X leaves the whole frame unchanged; it is copied byte for byte.
All cues and exclusions are listed in tables with Remove buttons. Undo (Ctrl+Z) steps back through changes to boxes, mode, cues and exclusions.
If every reference box is ignored or unusable on a frame, the frame is left unchanged and marked unresolved.

7. Review

Review step listing frames 30 to 32 where the reference boxes disagree, and a dip in the corrected graph — Before box B was ignored: step 4 lists frames 30–32 because boxes A and B disagree by more than 90%, and the corrected line in the graph dips there.

Review step with corrected view enabled and a flat corrected graph — After ignoring box B on those frames: nothing needs attention and the corrected line is flat within each segment. `B` switches the viewer between original and corrected.

Press Play (or Space) to watch the flip-book at 6, 8, 12 or 24 fps; tick Show corrected (or press B) to compare. Click the graph to jump to a frame.
“Boxes disagree” is only a hint: DazhLight cannot see what entered a box. Look at the frame and decide.
Frames whose gain was limited or that stayed unresolved must be acknowledged with the tick box before export.
The clipping warning in review is an estimate from the preview; gains.csv and report.html give the exact percentage of pixels that reach pure white. Lost highlights cannot be restored.

8. Export and reopen

Export step after a successful export with the summary message — Step 5 after export: the ZIP is in your downloads folder; your original frames are untouched.

The ZIP contains one folder with:

frames/ — corrected PNG frames under the original names (only the extension becomes .png), plus byte-identical copies of frames you left unchanged;
gains.csv — frame, source and output names, segment, status, boxes used, red/green/blue gains, exact clipped percentage, check-box brightness before/after and notes;
report.html — the graph, settings, warnings and a per-frame table; it contains no scripts;
settings.json — boxes, cues, mode and exclusions, bound to your frames by name, size and SHA-256;
manifest.json — SHA-256 of every source and output frame.

The exported report opened in Chrome showing the before and after graph — The exported `report.html` opened in Chrome.

To continue later, open the same frames and use Load settings… with the exported settings.json. Settings are refused if any frame's name, size or content differs, so they are never applied to another shot by mistake. Opening another set of frames clears the boxes, cues, exclusions and results of the previous shot; every export contains its settings.json. Import the frames/ folder into your editor as an image sequence as you would any PNG sequence.

DazhLight in a narrow 390 pixel wide window — Narrow window (390 px): the steps, viewer and panel stack vertically.

9. What it cannot fix

It applies one gain per frame (or one per colour channel). It cannot fix local flicker such as a shadow of the animator on part of the set, rolling LED bands, a moving camera, focus breathing or a puppet whose own lighting changes.
It does not read RAW files, TIFF, HEIC or video.
It does not detect occlusion: it only flags boxes that disagree. You decide what to ignore.
It cannot restore highlights that are clipped in the source or by a gain above 1.
No claims are made about Dragonframe, video editors or other applications beyond writing standard PNG files.

10. Troubleshooting

Message or symptom	What to do
“embedded colour profile”	Re-save the frames as sRGB without an embedded profile, then open them again.
“EXIF orientation …”	Rotate the frames for real (not just the orientation flag) in a photo editor.
“every frame must have the same size”	A frame was cropped or exported at another size. Re-export it at the shot size.
“more than one naming pattern” or “used by both”	Select the frames of one shot only, with one number per frame.
“limit is 300” or “120 million pixels”	Split the shot into parts at a cue or cut and correct each part separately.
“larger than 8 MiB” or “the limit is 256 MiB”	Save the frames as high-quality JPEG (usually much smaller than PNG) or split the shot.
“could not be read (was it moved, changed or deleted after you chose it?)”	A selected file was moved, overwritten or deleted after you chose it (for example by a re-export running at the same time). Choose the frames again when the files are final.
“will be applied as soon as all frames have been checked”	Nothing to do: the settings file waits for the frame check, then it is applied and the frames are measured.
“the browser could not decode this file”	The file is damaged or incomplete (for example an interrupted copy). Copy or export that frame again.
“The export would be larger than 512 MiB”	Split the shot into shorter parts. Your frames were not changed.
Boxes disagree on some frames	Step through them. If something covers a box, ignore that box on those frames.
Box too dark / clipped highlights in box	Move the box to a mid-tone static area.
Export button disabled	Measure the frames and confirm the review tick box if frames were limited or unresolved.
“changed on disk after it was opened”	A source file changed. Open the shot again.
Export cancelled	A setting changed during export. Press Export ZIP again.

11. Privacy

DazhLight runs entirely in your browser from DazhLight.html. Its content security policy blocks network connections; frames, settings and results stay on your computer. It writes nothing except the ZIP you export, and it never changes your source frames. Exported corrected frames do not carry the source metadata.

12. Uninstall

Delete the unzipped DazhLight folder. DazhLight stores no settings, caches or other files elsewhere; exported ZIPs remain wherever you saved them.