run-hncs
Run, build, test, smoke-test or screenshot the Hncs camera color-science project - apply a brand look to a photo, render a contact sheet of every shipped look, run the CLI tools (LUT export, RAW→Log, video, brand classifier), or check which entry points work in this checkout. Use when asked to run Hncs, render/preview a brand look, verify apply_* output, or reproduce a research experiment.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 16
- Forks
- 2
01 前言 Front Matter
- name
- run-hncs
- description
- Run, build, test, smoke-test or screenshot the Hncs camera color-science project - apply a brand look to a photo, render a contact sheet of every shipped look, run the CLI tools (LUT export, RAW→Log, video, brand classifier), or check which entry points work in this checkout. Use when asked to run Hncs, render/preview a brand look, verify apply_* output, or reproduce a research experiment.
02 资源文件 1
- 脚本driver.py11.9 KB
03 SKILL.md 正文
Running Hncs
Python image-in/image-out library (brands/*.py apply_* functions) plus
9 user-facing CLIs under tools/cli/ (plus ~140 research scripts elsewhere
under tools/). No server. There is a Tkinter GUI (python3 -m gui), but it
needs a display and a Python built with tkinter, so it isn't the agent
path — the equivalent of a screenshot here is a rendered output image you
actually open and look at.
Driven by .claude/skills/run-hncs/driver.py. All paths below are
relative to the repo root, and everything must run from the repo root
(the core/brands/tools imports are path-relative).
Prerequisites
Already present in the standard container. On a bare machine:
pip install -r requirements.txt
apt-get install -y libimage-exiftool-perl # hybrid_engine + contributed-data verification
darktable-cli (apt-get install -y darktable, ~180 packages) is needed
only to reproduce tools/research/evaluate_darktable_vs_rawpy.py. Nothing else
uses it.
Check what this checkout can actually run
Most interesting entry points need image corpora that are git-ignored, so a fresh clone can run far less than the README implies. Start here:
python3 .claude/skills/run-hncs/driver.py env
Prints dependency status, external binaries, and dataset presence:
== 데이터셋 (전부 .gitignore - 신선한 클론엔 없음) ==
OK raw_calib_cache/ 30개 - 핫셀블라드 raw+jpeg 13쌍 - calibrate / evaluate_* / hybrid_engine.main
OK downloaded_samples/ 123개 - population 샘플 - tools.cli.analyze (없으면 네트워크에서 받음)
OK raw_calib_cache_fuji/ 10개 - 후지 raw+jpeg 3쌍 - evaluate_fuji_demosaic
Run (agent path)
Smoke — everything that works with no external data
python3 .claude/skills/run-hncs/driver.py smoke
Exercises the library entry point plus 5 CLIs, exits non-zero on any
failure. Takes ~1 min (the denoise step dominates). Verified output:
PASS 라이브러리: apply_hncs 직접 호출
PASS CLI: tools.cli.export_lut --list
PASS CLI: tools.cli.export_lut (17격자 .cube 생성)
PASS CLI: tools.cli.classify_brand predict
PASS CLI: tools.cli.denoise
PASS CLI: hybrid_engine.convert (--source 필수)
6 pass / 0 fail
Contact sheet — the visual verification
python3 .claude/skills/run-hncs/driver.py sheet
# -> /tmp/hncs_run/contact_sheet.png (57 tiles: original + 56 looks, 2026-09-25)
Then open the PNG and look at it. Distinct looks should be obvious:
eterna_cinema teal, nostalgic_neg magenta-shifted, acros/
monochrome black-and-white, hncs brightened warm, the ten
population-fit brands subtler. Uniform tiles = the pipeline is broken.
This is the one command that proves the whole rendering path end-to-end.
One look at full resolution
python3 .claude/skills/run-hncs/driver.py look hasselblad
python3 .claude/skills/run-hncs/driver.py look astia --src photo.jpg --out /tmp/out.png
Accepts a bare brand (hasselblad), a preset (astia), or the full
function name (apply_canon_look). Unknown name prints the full list.
With no --src it crops a clean frame out of a committed demo image, so
it works with no data at all.
Output dir defaults to /tmp/hncs_run; override with HNCS_DRIVER_OUT.
Direct invocation (what most PRs touch)
Changes here are usually to a single apply_* or a core/ helper. Skip
the CLI entirely:
python3 -c "
import cv2
from brands.hasselblad import apply_hncs
src = cv2.imread('docs/images/before_after_hncs.jpg')[60:, :903]
cv2.imwrite('/tmp/out.png', apply_hncs(src))
"
Tests
python3 -m unittest discover -s tests # 1442 tests (2026-09-25), ~40s, no external data needed
Run (CLI tools individually)
All verified working in this container:
python3 -m tools.cli.export_lut --list
python3 -m tools.cli.export_lut hasselblad /tmp/hb.cube --size 17
python3 -m tools.cli.classify_brand predict /tmp/hncs_run/_smoke_src.jpg
python3 -m tools.cli.denoise in.jpg out.jpg --strength 5
python3 -m tools.cli.video_engine in.mp4 out.mp4 --brand hasselblad
python3 -m hybrid_engine.convert in.jpg out.jpg --source nikon --target hasselblad
python3 -m tools.cli.raw_pipeline raw_calib_cache/00378.jpg.3FR /tmp/o.tiff --log-space V-Log
The last one needs a RAW file — any .3FR/.RAF/.CR3/.ARW works, but
raw_calib_cache/ is git-ignored, so supply your own on a fresh clone.
Gotchas
hybrid_engine.converthard-fails on an image with no EXIF —EXIF로 소스 브랜드를 못 알아봄 (Make=None, Model=None), exit 1. Any image written bycv2.imwritehas no EXIF, so anything you generate mid-pipeline hits this. Pass--source nikon(or whichever brand).tools.cli.lens_correctionhard-fails the same way —--focal-length가 없고 EXIF에 FocalLength도 없음. Pass--focal-lengthand--apertureexplicitly.tools.cli.analyze <brand>is not read-only. It downloads the sample corpus (139 images forhasselblad) into git-ignoreddownloaded_samples/on first run — it only skips what's already cached (os.path.exists). Needs network plus the allowlisted domains in.claude/settings.json. Don't run it casually to "see what it does."apply_acrosandapply_monochromereturn 2D single-channel, not 3-channel BGR — deliberate, pinned bytest_mono_presets_return_single_channel, and whyexport_lutrefuses them (알 수 없는 preset: fuji_acros). Anything tilingapply_*output mustcv2.cvtColor(out, cv2.COLOR_GRAY2BGR)first. The driver does.docs/images/*.jpgare composites with baked-in labels, not clean source photos. The top ~60px is a label bar andbefore_after_hncs.jpgis a side-by-side pair. Crop[60:, :width//2]for a usable frame —driver.py'sdefault_source()does exactly this.colour-scienceprints a matplotlib warning on every import. Harmless noise, appears in front of real output; filter it when reading logs.- Research scripts (
tools/evaluate_*.py) take hours, not minutes — the chromatic-aberration one ran ~2h on 13 RAW pairs. Background them and watch the log; seetools/CLAUDE.md.
Troubleshooting
| Symptom | Fix |
|---|---|
ModuleNotFoundError: No module named 'core' |
You're not in the repo root. cd there. |
EXIF로 소스 브랜드를 못 알아봄 |
Add --source <brand> to hybrid_engine.convert. |
--focal-length가 없고 EXIF에 FocalLength도 없음 |
Add --focal-length N --aperture N to tools.cli.lens_correction. |
알 수 없는 preset: fuji_acros from export_lut |
Expected — monochrome presets are excluded from LUT export. Use --list. |
could not broadcast input array from shape (H,W) into (H,W,3) |
You got a mono preset's 2D output. cv2.cvtColor(out, cv2.COLOR_GRAY2BGR). |
FileNotFoundError under raw_calib_cache/ |
Git-ignored dataset absent. Run driver.py env to confirm, then supply your own RAW+JPEG pairs. |
| Sheet tiles all look identical | Real breakage in the shared curve/engine code — check core/curve.py and core/engine.py. |
04 同仓库更多 Skills
widen-the-solution-space
Deliberately widen the set of candidate approaches before committing to one. Use before irreversible decisions (architecture, DB schema, data format, public API), when the first solution feels complicated or awkward, when the user is deciding rather than instructing ("what's the best way to do this?"), or when a previous attempt at the same problem failed. Skip for routine work with one obvious answer.
weigh-tradeoffs
Compare real alternatives explicitly and record why one was chosen. Use when picking between libraries, data structures, architectures, or storage options; when a decision is hard to reverse (schema, public API, data format, dependency); or when the user asks "which is better, A or B". Also use to decide how much deliberation a decision even deserves.
verify-before-claiming
Run the verification and read its output before saying anything is done, fixed, working, or passing. Use before any completion claim, before committing or opening a PR, before moving to the next task, and after a subagent or tool reports success. Triggers on the words "should work", "fixed", "done", "passing", "looks good" — and on the urge to celebrate.
verifiability-first
Turn the task into something verifiable and declare the success criterion before seeing results. Use when the request is vague about "done" ("make it work", "improve this"), when writing tests, when fixing a bug (write the failing reproduction first), or when comparing two approaches. Critical before any measurement or benchmark, where deciding the bar after seeing the numbers guarantees a "success".
threat-and-scale-check
Check trust boundaries, scale behavior, and layered safety. Use when handling user input, external API responses, files, or auth; when designing permissions, validation, or any safety mechanism; when data volume could grow; or when writing loops that touch I/O. Also use when reviewing whether a single safeguard is the only thing standing between a mistake and a disaster.
surgical-change
Keep every changed line traceable to the request. Use when editing existing code, especially code you didn't write; when tempted to clean up something you noticed while reading; when a diff is growing beyond the ask; or when deciding whether to delete code that looks dead.