v0.2.3

What's New

Added

• NasalMorphometry module for computing nasal ratios from Varghaei et al. (2025)
• FacialSymmetry bilateral symmetry scoring via KDTree-based matching
• FaceLandmarks.pixel_coords_at() for getting coordinates at any resolution
• FaceLandmarks.rescale() for creating resolution-adjusted copies
• collect_instagram_data.py script for curating public-domain training pairs
• Competitive landscape table in README (9-method comparison)

Fixed

• DisplacementModel.load() now raises ValueError on corrupted/empty .npz files instead of returning zero-initialized model (#113)
• get_face_embedding() guards against near-zero ArcFace embeddings from occluded faces, preventing NaN similarity scores (#129)
• CUDA OOM during inference now raises an informative RuntimeError instead of hanging (#105)
• pixel_coords scale after image resize (#109)
• Remaining print() calls migrated to logging module (#288)

Full Changelog: v0.2.2...v0.2.3

What's Changed

• Remove duplicate root-level doc files by @dreamlessx in #247
• Add Mermaid architecture diagram to README by @dreamlessx in #248
• Add social preview image by @dreamlessx in #249
• Add project logo by @dreamlessx in #250
• Add procedure comparison demo grids by @dreamlessx in #251
• Fix PyPI publish: decouple from test-pypi failure by @dreamlessx in #252
• Add pipeline demo images and codecov badge to README by @dreamlessx in #253
• Replace face-containing demo images with abstract visualizations by @dreamlessx in #254
• Replace face-containing demos with abstract visual assets by @dreamlessx in #255
• Restore face demos, polish logo and social preview, fix flaky test by @dreamlessx in #256
• Redesign logo with golden decagon matrix by @dreamlessx in #257
• Fix logo: use PNG for GitHub rendering by @dreamlessx in #258
• Redesign logo: clean theatrical mask by @dreamlessx in #259
• Center mask in logo by @dreamlessx in #260
• Replace logo with canonical face mesh wireframe by @dreamlessx in #261
• Remove unused logo.svg and fix README TOC by @dreamlessx in #262
• Sync docs version to 0.2.2 by @dreamlessx in #264
• Fix critical DDP training bugs by @dreamlessx in #265
• Add brow_lift and mentoplasty to all default procedure lists by @dreamlessx in #268
• Fix ruff format violation breaking CI by @dreamlessx in #266
• Polish repo metadata, fix CI, and enable GitHub Pages by @dreamlessx in #267
• Fix E501 lint violations from procedure list expansion by @dreamlessx in #270
• Align arcface architecture with InsightFace weights by @dreamlessx in #271
• Port critical bug fixes from private repo by @dreamlessx in #272
• Polish README with centered banner and improved layout by @dreamlessx in #273
• Improve CONTRIBUTING.md with clearer setup and PR checklist by @dreamlessx in #274
• test: add unit tests for histogram_match_skin boundary and edge cases by @lshariprasad in #263
• Fix indentation in histogram_match_skin tests by @dreamlessx in #275
• Upgrade CI workflows to Node.js 24 action versions by @dreamlessx in #276
• Add lshariprasad and dagangtj to contributors list by @dreamlessx in #278
• Add Docker GPU support and deployment docs by @dreamlessx in #279
• Port training infrastructure improvements by @dreamlessx in #280
• Improve test coverage for critical code paths by @dreamlessx in #281
• Improve code quality: logging, constants, exceptions by @dreamlessx in #282
• Use weights_only=True for all torch.load calls by @dreamlessx in #284
• Replace remaining print() with logger in run_inference by @dreamlessx in #286
• Port script improvements and clean up error handling by @dreamlessx in #287
• Migrate remaining print() calls to logging module by @dreamlessx in #288
• Add morphometry evaluation and competitive landscape by @dreamlessx in #289
• Validate displacement model on load by @dreamlessx in #290
• Add rescale support for FaceLandmarks by @dreamlessx in #291
• Guard against NaN ArcFace scores on occluded faces by @dreamlessx in #292
• Catch CUDA OOM with informative error message by @dreamlessx in #293
• Release v0.2.3 by @dreamlessx in #294

New Contributors

• @lshariprasad made their first contribution in #263

Full Changelog: v0.2.2...v0.2.3

v0.2.2

What's New in v0.2.2

Added

• LCM-LoRA fast inference mode (4-step generation via latent consistency distillation)
• Per-procedure validation with anatomy-aware rejection
• 26 new utility scripts (evaluation, visualization, paper figures)
• Bilateral symmetry analysis with per-region scoring
• Expanded GitHub wiki to 15 pages
• Real demo faces in HF Space
• Comprehensive clinical motivation and competitor comparison in docs
• 3D reconstruction vision and roadmap (v0.4.0+)

Changed

• bf16 is now the default training precision
• HF Space UI streamlined with gradient header and procedure descriptions
• Documentation restructured around phone-video -> 3D vision

Fixed

• Inference dtype mismatch between fp16/bf16 checkpoints
• Per-procedure validation skip when --validate flag absent
• CI lint fixes for community-contributed code

Community

• Brow lift preset by @Deepak8858 (PR #35)
• Mentoplasty preset by @P-r-e-m-i-u-m (PR #36)
• SafetyResult improvements, file logging, and API error handling by @dagangtj (PRs #235-237)

Stats

• 2292 tests passing across Python 3.10/3.11/3.12
• 6 procedures, 4 inference modes, 5 clinical flags
• Fitzpatrick I-VI stratified evaluation

---

Full Changelog: See CHANGELOG.md
Live Demo: huggingface.co/spaces/dreamlessx/LandmarkDiff
Roadmap: docs/ROADMAP.md

What's Changed

• feat: add brow lift procedure preset by @Deepak8858 in #35
• feat: add mentoplasty (chin surgery) preset by @P-r-e-m-i-u-m in #36
• Add comprehensive wiki pages (Installation, Quick-Start, Benchmarks) by @dreamlessx in #223
• Add repr and eq to SafetyResult dataclass by @dagangtj in #235
• Add file logging handler option to log.py setup_logging() by @dagangtj in #236
• Improve error messages in api_client.py for connection failures by @dagangtj in #237
• Update README with 3D reconstruction vision by @dreamlessx in #238
• Restructure roadmap around 3D reconstruction vision by @dreamlessx in #239
• Add 3D reconstruction contribution areas to docs by @dreamlessx in #240
• Expand clinical motivation and competitive landscape in README by @dreamlessx in #241
• Polish README cohesion and flow by @dreamlessx in #242
• Standardize terminology and cross-references across docs by @dreamlessx in #243
• Update HF Space description with 3D vision by @dreamlessx in #244
• Fix HF Space short_description length by @dreamlessx in #245
• Fix reference errors and documentation inconsistencies by @dreamlessx in #246

New Contributors

• @Deepak8858 made their first contribution in #35
• @P-r-e-m-i-u-m made their first contribution in #36
• @dreamlessx made their first contribution in #223
• @dagangtj made their first contribution in #235

Full Changelog: v0.1.0...v0.2.2

v0.1.0 - Initial Public Release

First public release of LandmarkDiff.

Whats included

• Full inference pipeline (4 modes: TPS, img2img, ControlNet, ControlNet+IP-Adapter)
• 4 procedure presets (rhinoplasty, blepharoplasty, rhytidectomy, orthognathic)
• MediaPipe 478-point landmark extraction and Gaussian RBF deformation
• Tessellation wireframe + adaptive Canny edge conditioning for ControlNet
• Feathered surgical mask generation with Perlin boundary noise
• Post-processing: CodeFormer, Real-ESRGAN, LAB histogram matching, Laplacian pyramid blending, ArcFace identity verification
• Clinical edge case handling (vitiligo, Bell's palsy, keloid, Ehlers-Danlos)
• Synthetic training pair generation via TPS warps
• ControlNet fine-tuning pipeline with Phase A/B loss scheduling
• Evaluation harness with FID, LPIPS, SSIM, NME, Identity Sim (Fitzpatrick-stratified)
• 5-tab Gradio demo with multi-angle capture
• Docker and Apptainer container support
• SLURM job scripts for HPC training

Whats next

• ControlNet fine-tuning on 50K+ synthetic pairs (in progress)
• See the roadmap for v0.2 plans

Install

pip install -e .