pfsalign(1)

💅 pfsalign(1) — General Commands Manual, but make it cute

okay bestie, so this is pfsalign from the General Commands Manual — the align-image-stack girlie. she's here to make your frames line up. let's go 🎀

---

✨ NAME ✨

pfsalign — align image stack. that's it, that's the whole job. slay.

---

🦋 SYNOPSIS 🦋

pfsalign [--reference <index>|-r <index>] [-c (min|max)|--crop
(min|max)] [-s val|--sensitivity val] [-f|--fail-no-match] [--display-
matches|-d] [--verbose] [--help]

---

💖 DESCRIPTION 💖

so like, use this command to align an image stack — think HDR merging, that kind of vibe. the command uses a feature-point-based matching method to find a homographic transformation that maps all the images in the stack onto the coordinates of the reference image. then it outputs the transformed (aligned) images, all at the same resolution. the input images can literally be different resolutions, no stress. it can fix a substantial misalignment caused by camera rotation (along any axis) and slight movement. main character energy fr 💫

the method is essentially similar to the one in this paper, and we're quoting it exactly so don't come for me:

Tomaszewska, Anna, and Radoslaw Mantiuk. "Image Registration for Multi-Exposure High Dynamic Range Image Acquisition." In International Conferences in Central Europe on Computer Graphics, Visualization and Computer Vision, pp. 49-56, 2007.

ngl though, the code is not based on the authors' implementation. separate girlies, same vibes.

the images get matched pairwise, in the same order as they're sent to the command. so make sure every consecutive image pair has overlapping parts, okay? 😭 when you're aligning multiple exposures, use pfsinme, which sorts exposures according to the shutter speed and therefore improves matching between image pairs. the command will assume no misalignment (or fail, if you passed the -f option) if there's no overlap, or if it can't find a sufficient number of features in one of the pairs.

⚠️ homographic alignment will not eliminate all misalignment artefacts. in particular it will not eliminate ghosting due to moving objects. the alignment algorithm assumes the effect of parallax is negligible — so if the camera moves rather than rotates and there are objects close to the camera, they will most likely remain misaligned. ghosting said "i'm staying" 💀

---

🌸 OPTIONS 🌸

• --reference <index>, -r <index> — index of the reference image. heads up: the first image has index 1. default: 1 (the first image).
• --display-matches, -d — display matching key-points for each image pair. super useful for inspecting what went wrong with key-point matching, iykyk 🔍
• --crop min|max, -c min|max — crop either to the image that contains all pixels (max) or to the image that contains only the pixels that overlap in all exposures (min). the min option will eliminate black (empty) pixels from all exposures. ate.
• --sensitivity value, -s value — higher sensitivity = detecting more feature points and potentially a better alignment, but also longer computation time. the value parameter must be in the range from 1 to 10. default: 5.
• --fail-no-match, -f — if this option is present, the program will exit with a fail status when no match was found for one or more of the image pairs. otherwise, the program will assume that the failed image pair is perfectly aligned (assume identity matrix as a homography).

🫶 also hanging out in the synopsis: --verbose and --help. they're listed up there, so go look, bestie.

---

🌈 EXAMPLES 🌈

okay these are the moment, fr fr:

pfsin img1.exr img2.exr | pfsalign -v -r 2 | pfsview

align two EXR images using the second image (img2.exr) as a reference. then preview the result. iconic.

pfsinme *.CR2 | pfssize  --maxx 1200 | pfsalign -v -c min  |
pfshdrcalibrate -r linear -v --bpp 16 | pfsout result.exr

align a stack of RAW image exposures (from a Canon camera), resize them so that the width is equal or less 1200 pixels, align the exposures, and merge them to an HDR image. the whole pipeline, chef's kiss 👑

---

⭐ SEE ALSO ⭐

• pfsin(1)

---

💀 BUGS 💀

the current implementation is rather inefficient in terms of memory management and can consume a considerable amount of memory. this is because of the pfstools architecture, which requires that all aligned frames must be loaded into memory. it should be possible to align 3-4 10-megapixels images for 1.5GB of available memory. so like... hydrate, and also close some tabs 😭

please report bugs and comments to the pfstools discussion group (http://groups.google.com/group/pfstools). they're lovely, i promise 🫶

---

okay that's the whole page!! mwah 💋 — this was pfsalign(1) straight out of the General Commands Manual, and yeah the footer said pfsalign(1) again because it's consistent like that ✨ go align something pretty 🦋🎀