cpfind - Feature matching for panoramic stitching


   cpfind [options] -o output_project project.pto

   cpfind [options] -k i0 -k i1 [...] project.pto

   cpfind [options] --kall project.pto


   cpfind cpfind is a control-point detector for Hugin. It expects a
   project file as input and writes a project file with control-points on
   success.  It depends on reasonable lens information in the input
   project file.

   The first step is the feature description: In this step the images of
   the project file are loaded and so called keypoints are searched. They
   describe destinctive features in the image. cpfind uses a gradient
   based descriptor for the feature description of the keypoints.

   In a second step, the feature matching, all keypoints of two images are
   matched against each other to find features which are on both images.
   If this matching was successfull two keypoints in the two images become
   one control point.


   Rectilinear and fisheye images
   Cpfind can find control points in rectilinear and fisheye images. To
   achieve good control points images with a high horizontal field of view
   (e.g. ultra wide rectilinear or fisheye) are therefor remapped into a
   conformal space (cpfind is using the stereographic projection) and the
   feature matching occurs in this space. Before writing the control
   points the coordinates are remapped back to the image space. This
   happens automatic depending on the information about the lens in the
   input project file. So check that your input project file contains
   reasonable information about the used lens.

   Using celeste
   Outdoor panorama often contains clouds. Clouds are bad areas for
   setting control points because they are moving object. Cpfind can use
   the same algorithm as celeste_standalone to masked out areas which
   contains clouds. (This is only done internal for the keypoint finding
   step and does not change the alpha channel of your image. If you want
   to generate a mask image use celeste_standalone). To run cpfind with
   celeste use

      cpfind --celeste -o output.pto input.pto

   Using cpfind with integrated celeste should be superior against using
   cpfind and celeste_standalone sequential. When running cpfind with
   celeste areas of clouds, which often contains keypoints with a high
   quality measure, are disregarded and areas without clouds are used
   instead. When running cpfind without celeste also keypoints on clouds
   are found. When afterwards running celeste_standalone these control
   points are removed. In the worst case all control points of a certain
   image pair are removed.

   So running cpfind with celeste leads to a better "control point
   quality" for outdoor panorama (e.g. panorama with clouds). Running
   cpfind with celeste takes longer than cpfind alone. So for indoor
   panorama this option does not need to specified (because of longer
   computation time).

   The celeste step can be fine tuned by the parameters --celesteRadius
   and --celesteThreshold.

   Matching strategy
   All pairs

   This is the default matching strategy. Here all image pairs are matched
   against each other. E.g. if your project contains 5 images then cpfind
   matches the image pairs: 0-1, 0-2, 0-3, 0-4, 1-2, 1-3, 1-4, 2-3, 2-4
   and 3-4

   This strategy works for all shooting strategy (single-row, multi-row,
   unordered). It finds (nearly) all connected image pairs. But it is
   computational expensive for projects with many images, because it test
   many image pairs which are not connected.

   Linear match

   This matching strategy works best for single row panoramas:

      cpfind --linearmatch -o output.pto input.pto

   This will only detect matches between adjacent images, e.g. for the 5
   image example it will matches images pairs 0-1, 1-2, 2-3 and 3-4. The
   matching distance can be increased with the switch --linearmatchlen.
   E.g. with --linearmatchlen 2 cpfind will match a image with the next
   image and the image after next, in our example it would be 0-1, 0-2,
   1-2, 1-3, 2-3, 2-4 and 3-4.

   Multirow matching

   This is an optimized matching strategy for single and multi-row

      cpfind --multirow -o output.pto input.pto

   The algorithm is the same as described in multi-row panorama. By
   integrating this algorithm into cpfind it is faster by using several
   cores of modern CPUs and don't caching the keypoints to disc (which is
   time consuming). If you want to use this multi-row matching inside
   hugin set the control point detector type to All images at once.

   Keypoints caching to disc

   The calculation of keypoints takes some time. So cpfind offers the
   possibility to save the keypoints to a file and reuse them later again.
   With --kall the keypoints for all images in the project are saved to
   disc. If you only want the keypoints of particular image use the
   parameter -k with the image number:

      cpfind --kall input.pto
      cpfind -k 0 -k 1 input.pto

   The keypoint files are saved by default into the same directory as the
   images with the extension .key. In this case no matching of images
   occurs and therefore no output project file needs to specified. If
   cpfind finds keyfiles for an image in the project it will use them
   automatically and not run the feature descriptor again on this image.
   If you want to save them to annother directory use the --keypath

   This procedure can also be automate with the switch --cache:

      cpfind --cache -o output.pto input.pto

   In this case it tries to load existing keypoint files. For images,
   which don't have a keypoint file, the keypoints are detected and save
   to the file. Then it matches all loaded and newly found keypoints and
   writes the output project.

   If you don't need the keyfile longer, the can be deleted automatic by

      cpfind --clean input.pto


   Feature description
   For speed reasons cpfind is using images, which are scaled to their
   half width and height, to find keypoints. With the switch --fullscale
   cpfind is working on the full scale images. This takes longer but can
   provide "better" and/or more control points.

   The feature description step can be fine-tuned by the parameters:

   --sieve1width <int>
       Sieve 1: Number of buckets on width (default: 10)

   --sieve1height <int>
       Sieve 1: Number of buckets on height (default: 10)

   --sieve1size <int>
       Sieve 1: Max points per bucket (default: 100)

   --kdtreesteps <int>
       KDTree: search steps (default: 200)

   --kdtreeseconddist <double>

   KDTree: distance of 2nd match (default: 0.25)

   Cpfind stores maximal sieve1width * sieve1height * sieve1size keypoints
   per image. If you have only a small overlap, e.g. for 360 degree
   panorama shoot with fisheye images, you can get better results if you
   increase sieve1size. You can also try to increase sieve1width and/or

   Feature matching
   Fine-tuning of the matching step by the following parameters:

   --ransaciter <int>
       Ransac: iterations (default: 1000)

   --ransacdist <int>
       Ransac: homography estimation distance threshold (pixels) (default:

   --ransacmode (auto, hom, rpy, rpyv, rpyb)
       Select the model used in the ransac step.

       hom: Assume a homography. Only applicable for non-wide angle
            views. Uses the original panomatic code. It is also more
            than required and can generate false matches, particularly if
            of the matches are located on a single line.

       rpy: Align images using roll, pitch and yaw. This requires a good
            estimate for the horizontal field of view (and distortion, for
            heavily distorted images). It is the preferred mode if a
            calibrated lens is used, or the HFOV could be read
            from the EXIF data.

       rpyv: Align pair by optimizing roll, pitch, yaw and field of
             view. Should work without prior knowledge of the field of
             but might fail more often, due to error function used in the
             panotools optimizer, it tends to shrink the fov to 0.

       rpyvb: Align pair by optimizing roll, pitch, yaw, field of view and
              the "b" distortion parameter.  Probably very fragile, just
              implemented for testing.

       auto: Use homography for images with hfov < 65 degrees and rpy

   --minmatches <int>
       Minimum matches (default: 4)

   --sieve2width <int>
       Sieve 2: Number of buckets on width (default: 5)

   --sieve2height <int>
       Sieve 2: Number of buckets on height (default: 5)

   --sieve2size <int>
       Sieve 2: Max points per bucket (default: 2)

       Cpfind generates between minmatches and sieve2width * sieve2height
       * sieve2size control points between an image pair. (Default setting
       is between 4 and 50 (=5*5*2) control points per image pair.) If
       less then minmatches control points are found for a given image
       pairs these control points are disregarded and this image pair is
       considers as not connected. For narrow overlaps you can try to
       decrease minmatches, but this increases the risk of getting wrong
       control points.


   --celesteRadius <int>
       Radius for celeste (default 20)

   --celesteThreshold <double>
       Threshold for celeste (default 0.5)

       Run celeste sky identification after loading images, this ignores
       all features associated with 'clouds'.

   -p <string, --keypath <string>
       Path to cache keyfiles

       Clean up cached keyfiles

   -c, --cache
       Caches keypoints to external file

       Write keyfiles for all images

   -k <int>, --writekeyfile <int>
       Write a keyfile for this image number (accepted multiple times)

   -o <string>, --output <string>
       Output file, required

   -n <int>, --ncores <int>
       Number of CPU/Cores (default:autodetect)

   -t, --test
       Enables test mode

       Uses full scale image to detect keypoints (default:false)

   --sieve1width <int>
       Sieve 1 : Number of buckets on width (default : 10)

   --sieve1height <int>
       Sieve 1 : Number of buckets on height (default : 10)

   --sieve1size <int>
       Sieve 1 : Max points per bucket (default : 100)

   --kdtreesteps <int>
       KDTree : search steps (default : 200)

   --kdtreeseconddist <double>
       KDTree : distance of 2nd match (default : 0.15)

       Enable heuristic multi row matching (default: off)

       Enable linear images matching (default : all pairs)

   --linearmatchlen <int>
       Number of images to match in linear matching (default:1)

   --minmatches <int>
       Minimum matches (default : 4)

   --ransaciter <int>
       Ransac : iterations (default : 1000)

   --ransacdist <int>
       Ransac : homography estimation distance threshold (pixels) (default
       : 25)

   --sieve2width <int>
       Sieve 2 : Number of buckets on width (default : 5)

   --sieve2height <int>
       Sieve 2 : Number of buckets on height (default : 5)

   --sieve2size <int>
       Sieve 2 : Max points per bucket (default : 2)

   --, --ignore_rest
       Ignores the rest of the labeled arguments following this flag.

       Displays version information and exits.

   -h, --help
       Displays usage information and exits.


   Anael Orlinski, Pablo d'Angelo, Antoine Deleforge, Thomas Modes

"Version: 2016.2.0"               2016-09-11                         CPFIND(1)

More Linux Commands

perl5100delta(1) - what is new for perl 5.10.0 (Man Page)...
This document describes the differences between the 5.8.8 release and the 5.10.0 release. Many of the bug fixes in 5.10.0 were already seen in the 5.8.X mainten

Tcl_PkgRequireProc(3) - package version control (Man Page)
These procedures provide C-level interfaces to Tcls package and version management facilities. Tcl_PkgRequire is equivalent to the package require command, Tcl_

XTextItem(3) - draw polytext text and text drawing structure
The XDrawText16 function is similar to XDrawText except that it uses 2-byte or 16-bit characters. Both functions allow complex spacing and font shifts between c

sigevent(7) - structure for notification from asynchronous r
The sigevent structure is used by various APIs to describe the way a process is to be notified about an event (e.g., completion of an asynchronous request, expi

gnutls_x509_crt_import(3) - API function - Linux man page...
This function will convert the given DER or PEM encoded Certificate to the native gnutls_x509_crt_t format. The output will be stored in cert. If the Certificat

XRectInRegion(3) - determine if regions are empty or equal
The XEmptyRegion function returns True if the region is empty. The XEqualRegion function returns True if the two regions have the same offset, size, and shape.

tee(1) - read from standard input and write to standard outp
Copy standard input to each FILE, and also to standard output. -a, --append append to the given FILEs, do not overwrite -i, --ignore-interrupts ignore interrupt

lss16toppm(1) Convert an LSS-16 image to PPM (Man Page).....
This manual page documents briefly the lss16toppm command. The lss16toppm utility converts an LSS-16 image to a PPM image. OPTIONS A summary of options is inclu

aligned_alloc(3) allocate aligned memory - Linux man page...
The function posix_memalign() allocates size bytes and places the address of the allocated memory in *memptr. The address of the allocated memory will be a mult

uwildmat(3) - Perform wildmat matching - Linux manual page
uwildmat compares text against the wildmat expression pattern, returning true if and only if the expression matches the text. @ has no special meaning in patter

termios(3) - get and set terminal attributes, line control,
The termios functions describe a general terminal interface that is provided to control asynchronous communications ports. The termios structure Many of the fun

Tcl_GetEnsembleNamespace(3) - manipulate ensemble commands
An ensemble is a command, bound to some namespace, which consists of a collection of subcommands implemented by other Tcl commands. The first argument to the en

We can't live, work or learn in freedom unless the software we use is free.