FOCUS-STACK(1)

📦
version 1.4 · 2 versions
, in opensuse-leap 16.0

💅 focus-stack 💅

okay so bestie, welcome to the manual page for focus-stack — it lives in section 1 of the manual, and honestly? it's kind of iconic. it's a command-line tool, it's got main character energy, and by the end of this page you're gonna understand it fr fr. grab a strawberry 🍓 and let's go.

✨ NAME ✨

focus-stack — combine photos to create an extended depth of field image 🌸

🎀 SYNOPSIS 🎀

focus-stack [options ...] file1.jpg file2.jpg ...

literally just throw your pics at it and it does its thing. no cap.

🦋 DESCRIPTION 🦋

okay so picture this: you've got a whole stack of photos, each one taken at a different focus setting, and none of them individually has the whole subject sharp. tragic, right? 😭 well focus-stack takes that entire set and combines them into one single image, picking the sharpest source image for each pixel position. that's the whole vibe.

this technique is commonly called extended depth of field, or focus stacking — iykyk. the typical use case is microscope photography, where getting a depth of field big enough to cover the whole subject is, like, genuinely difficult. so instead of fighting the laws of optics, you just stack. periodt. 👑

usually you get good results with the default settings (the defaults ate, honestly), but these options are available:

🌈 Output file options 🌈

  • --output=output.jpg — set the output filename. heads up: if the file already exists, it gets overwritten, no questions asked 💀. the format is decided by the file extension, and the formats currently supported by OpenCV are .bmp, .jpg, .jp2, .png, .webp, .ppm, .pfm, .sr, .tif, .exr and .hdr.
  • --depthmap=depthmap.png — generate a depthmap image, which shows the depth layers determined from the image stack. brightness gets scaled from 0 to 255, where 0 is the first image given on the command line and 255 is the last image. cute little depth gradient ✨
  • --3dview=3dview.png — based on the depth map, generate a 3-dimensional preview image. yes, we're going 3D, it's giving sci-fi 🛸
  • --save-steps — save intermediate images from the processing steps. this includes the aligned images and the final grayscale image before color reassignment. for the girlies who wanna see the process 🎀
  • --jpgquality=95 — set the level of quality of the JPEG files (final and intermediates, if you asked for those to be written). the value can go from 0 to 100, with a default at 95.
  • --nocrop — keep the full size of input images. by default images get cropped to the area that's valid for all images in the input stack, to avoid distortion near the edges. so --nocrop is the "don't touch my borders" option 💅

💜 Image alignment options 💜

  • --reference=index — select the image index (starting from 0) to use as the alignment reference. images in a stack usually vary in scale and position, so all the other images get resized and rotated to match this one. this also determines the scale of the output image, which is important for performing measurements. by default the middle image of the stack is used as the reference. 🎯
  • --global-align — by default each image is aligned against its neighbour. this improves results in deep stacks, since blur at the extreme focus levels can make direct alignment to the reference inaccurate. however — and this is a big however — if the images given as arguments are not in the correct order, or if some of them are of poorer quality, you can specify this option to align directly against the reference image instead. know your stack, bestie 🙈
  • --full-resolution-align — by default the resolution of images used in the alignment step is limited to 2048x2048 pixels. this improves performance, and because sub-pixel accuracy is used in computing the gradients, a higher resolution rarely improves results. specifying this option forces the use of full resolution images in alignment. expensive but brave 💸
  • --no-whitebalance — the app tries to compensate for any white balance differences between photos automatically. if the camera white balance is set manually, you can specify this option to skip the unnecessary white balance adjustment.
  • --no-contrast — if camera exposure is manually controlled, this option can be used to skip unnecessary exposure compensation. manual girlies stay winning 🫶
  • --align-only — only align the image stack and exit. useful for further processing of the aligned images with external tools. sometimes you just want the alignment and nothing else, and that's valid.

🧚 Image merge options 🧚

  • --consistency=level — set the level of consistency filter applied to the depth map, in range 0 to 2. a higher level reduces artefacts and noise in the output image, but it can also result in removing small objects that appear against a textured background. by default the highest filter level, 2, is used. trade-offs, always trade-offs 😭
  • --denoise=level — set the level of the wavelet-based denoise filter applied to the result image. because focus stacking selects the largest difference from the source images, it has a tendency to increase noise. the denoising step reduces all wavelet values by this amount, which corresponds directly to pixel values. the default value of 1.0 removes noise that is on the order of ± 1 pixel value. tiny cleanup, big glow-up ✨

⭐ Depth map generation options ⭐

  • --depthmap-threshold=level — minimum contrast in the input image for accepting as a data point for depth map building. range 0-255, default 10.
  • --depthmap-smooth-xy=level — smoothing of the depthmap in the image plane. the value is a radius in pixels.
  • --depthmap-smooth-z=level — smoothing of the depthmap in the depth direction. the value is in 0-255 units.
  • --remove-bg=threshold — add an alpha channel to the depthmap and remove constant colored background. the threshold is positive for a black background and negative for a white background. 🖤🤍
  • --halo-radius=level — reduce halo effects in the depthmap near sharp contrast edges. the value is a radius in pixels.
  • --3dviewpoint=x:y:z:zscale — viewpoint used for the 3D preview. specifies the x, y and z coordinates of the camera and the z scaling of the depthmap values. camera girlies rise 🎥

🔥 Performance options 🔥

  • --threads=count — set the number of parallel threads in use. by default it uses the number of CPU cores detected plus one, to feed a possible GPU accelerator. a lower number of threads also reduces memory consumption.
  • --batchsize=count — set the batch size for image merging. larger values may give slightly better performance on machines with a large amount of memory, while smaller values reduce memory usage. currently the default value is 8 and the maximum value is 32.
  • --no-opencl — by default OpenCL-based GPU acceleration is used if available. this option can be specified to disable it. (why would you? no judgement. some of us just like CPU vibes.)
  • --wait-images=seconds — wait for the given time if any image files are missing. specifying this option allows you to start processing before all image files have been captured from the camera. it's giving "patience is a virtue" ⏳

💖 Information options 💖

  • --verbose — report each step as it begins and ends, and also the alignment parameters and other detailed information. for the girlies who need to know everything 💬
  • --version — show application version number.
  • --opencv-version — show OpenCV library build information.

🌸 EXAMPLES 🌸

  • focus-stack IMG*.JPG — combine all images in the current directory, and write output to output.jpg.
  • focus-stack --verbose --output=stacked.png IMG*.JPG — combine all images, giving a detailed printout of steps, and write output to stacked.png.
  • focus-stack --jpgquality=100 IMG*.JPG — generate a JPEG with the maximum quality level. max quality, max slay 💅

🫶 GPU ACCELERATION 🫶

this application uses the OpenCV library and its OpenCL acceleration interface. the GPU used for acceleration can be selected by the environment variable OPENCV_OPENCL_DEVICE, which takes a value such as Intel:GPU:0. see the OpenCV documentation for details. ngl, environment variables are lowkey iconic.

📚 REFERENCES 📚

the algorithm used for combining images is described in Complex Wavelets for Extended Depth-of-Field: A New Method for the Fusion of Multichannel Microscopy Images by B. Forster, D. Van De Ville, J. Berent, D. Sage and M. Unser. cite your sources, bestie 🎓

🐛 REPORTING BUGS 🐛

bugs can be reported at https://github.com/PetteriAimonen/focus-stack/issues — be nice, bring a reproduction, and remember: the maintainers are people too 💜

ok that's the whole page!! go stack some photos, you've got this 💖

and that's a wrap, bestie — this page is from May 2022, and the source/version line at the bottom is just the manual title FOCUS-STACK() showing up one last time to say bye. mwah 🎀✨💅

📦 where this page comes from