Man Linux: Main Page and Category List

NAME

       autopano - Generate panorama project from SIFT keypoint files.

SYNOPSIS

       autopano     [options]     output.pto    keyfile1[.gz]    keyfile2[.gz]
       [keyfile3[.gz] [..]]

DESCRIPTION

       Generate panorama project from keypoint data. First,  read  in  two  or
       more  SIFT keypoint files, then correlate the keypoint data and build a
       list of matches.  This list  undergoes  some  filtering  and  the  best
       matches are used to create control point information. The control point
       information are writting to a PTO compatible panorama project file. For
       example, programs such as hugin can read it.

       Prior  to any further use of the PTO, you ABSOLUTELY HAVE TO ADJUST THE
       FOCAL LENGTH of all the images. This can  be  done  in  hugin,  in  the
       "Camera and Lens" tab.

OPTIONS

       --ransac <on|off|1|0>
              Switch RANSAC postfiltration on or off. Default is on. There are
              only a few reasons to switch this off: if the  keypoint  density
              and  matches are very sparse, RANSAC may filter too much. Or, if
              the lens geometry used is unusual (fish eye,  very  wide  angle,
              micropanorama,   ...)   and  does  not  resemble  a  rectilinear
              projection. That is, if you get really bad results  with  RANSAC
              on, disable it.

       --maxmatches <count>
              Set  the  maximum  number  of  control  point  pairs you want to
              generate per image pair. The default is 16, so  for  each  image
              pair,  there  are  no  more than 16 control points generated. If
              there  are  more  control  points  to  choose  from,   an   area
              maximization  metric  is  applied to keep the matches that cover
              most of the image area. You can disable this by setting count to
              zero. Then all matches are kept.

       --disable-areafilter
              At  the  final stage of creating control points, there is a list
              of matches for every image pair that overlaps. All this  matches
              are  thought  to  be  correct  and  have been filtered using the
              RANSAC  algorithm.  However,  often  there  are   more   matches
              available  than  the  user wants to keep (see the "--maxmatches"
              option).  In previous versions we applied  a  simple  metric  to
              pick  out  the  matches that have a good matching score. Now, we
              have an area maximization algorithm,  that  maximizes  the  area
              covered  by  the  matches.  In  general,  this  leads  to better
              coverage of the image overlap area. However, if you want the old
              behaviour,  that only considers the SIFT matching score of every
              match, enable this option.

       --integer-coordinates
              Use natural number coordinates in the PTO  file  for  the  found
              matches.   Default  is  to  use  sub-pixel  float coordinates to
              increase precision.  You may want to try this option in case you
              use another frontend than hugin and you experience problems with
              the PTO files created by autopano-sift.

       --absolute-pathnames <on|off|1|0>
              Store the absolute pathnames of the image files in the PTO file.
              Normally,  in  case all images are in the same directory and the
              output PTO file is also saved in this directory, only the  image
              filenames  are used.  Otherwise the absolute pathnames are used.
              Using this option you can enforce the behaviour.

       output.pto
              The filename of the PTO project file to generate.

       keyfile[.gz]
              The  SIFT  XML  keypoint  data  file,  as  generated  with   the
              generatekeys(1)   program.   If  the  filename  ends  in  ".gz",
              transparent gzip(1) decompression is used.

ALIGN OPTIONS

       --align
              Enable fully automatic pre-aligning algorithm. This  results  in
              yaw, pitch and rotation coordinates being assigned to the images
              in the resulting PTO file.  This option is not perfect yet,  but
              in most cases the result is far better than without using it.

              There are a number of conditions on the input images that can be
              used with this algorithm. First, the images should all be of the
              same  dimension,  scale and have a simple (rectangular) geometry
              with roughly euclidean distances. Second, the order of the input
              images  is  considered so that the first images build an ordered
              row on the horizon. That is,  the  first,  second,  third,  etc.
              images  are  strictly aligned left-to-right or right-to-left and
              all lie roughly on the horizon. They must also  all  be  of  the
              same  rotation  angle,  which  must be one of three rough cases:
              bottom-is-bottom, bottom-is-left, bottom-is-right. Bottom-is-top
              is  forbidden.  In  case  the bottom is either left or right, we
              estimate its position based on average  keypoint  density  (also
              experimental).

              In  case  the horizontal first row is not properly detected, try
              to increase the downscale resolution when creating the  keypoint
              data.  This will produce more keypoints which makes it easier to
              build the horizont-row. In case it  still  does  not  work,  you
              should  not  enable this option. Please report bugs or successes
              with this option.

       --bottom-is-left

       --bottom-is-right
              Only usable if --align option is enabled. If your  input  images
              are  90  or  -90  degree  tilted for the first row of horizontal
              images, you can force the orientation  by  telling  the  program
              where  the  bottom (floor) of the images is located: on the left
              or right side. If this option is  not  used,  the  program  will
              attempt to automatically figure the orientation based on average
              keypoint density in the left and right half of the image.

       --generate-horizon <count>
              Generate a horizon from the  first  row  of  aligned  horizontal
              images.  This can only be used if the --align option is enabled.
              Then, up to count number of horizon control  lines  are  written
              into  the  resulting  PTO  file  at  the middle of the first row
              images. The lines are optimally spaced and you should use values
              such  as  2, 6 or 14 to get optimal results (the sum of power of
              two, starting with 2, 2 + 4, 2 + 4 + 8).

REFINEMENT OPTIONS

       --refine
              Enable the refinement step.  The refining is done as  last  step
              before  writing the PTO output file.  For every matching control
              point pair a small patch in the original images is extracted  at
              the  original resolution.  The image patches are matched against
              each other  with  the  highest  possible  quality  of  matching,
              usually  yielding  dozens  of  keypoints.   As  this matches are
              derived from the original resolution image,  their  location  is
              more  precise  and they are used to refine the original keypoint
              using one of the two methods  below.   Note  that  enabling  the
              refinement  step makes the total process longer, hence it is not
              enabled by default.

       --refine-by-middle

       --refine-by-mean
              Two methods are available to choose the best point from the high
              resolution matches.  Refine by middle searches the match closest
              to the original keypoints position and keeps  only  this  match.
              Refine  by  mean  builds  the  geometric center of all keypoints
              found in the patch and uses this coordinates.

       --keep-unrefinable <on|off|1|0>
              In case a good match cannot be refined because it is located  to
              near to the boundary of the image, the original match is kept by
              default.  To disable this behaviour, you can  use  this  option,
              which  throws away matches that cannot be refined.  However, you
              might want to increase the number of matches to keep  per  image
              pair using the "--maxmatches" option then.

COMPONENT IDENTIFICATION

       The  program  complains about non-connected components in case there is
       one or more images or image groups which have no  relationship  to  the
       rest of the images. This means there is no way to jump from an image in
       one group to another  group  by  just  following  control  point  pairs
       between  any  two images.  This component identification is crucial for
       further optimization: if there is one or more non-connected components,
       global optimization based on control point pairs will be impossible.

       To  fix  this  problem,  first  identify  the  reason  why there are no
       keypoint matches between the images  in  the  different  components.  A
       common  reason is that the images in one component are very diffuse and
       only have very few control points (such as images of the sky or water).
       If  this  is  the case, you can try to increase the number of keypoints
       found in each image by increasing the downscaleResolution parameter  of
       the generatekeys(1) program. Or you can add control point pairs between
       the images of the individual components manually, using  software  such
       as  hugin.  Another  reason  for different components could be that the
       images do not belong together to one panorama.

COMMON PROBLEMS

       PTO does not optimize/render in hugin. Please check that  you  adjusted
       the   camera  lens  or  focal  length  parameter  for  each  image.  We
       intentionally set it to a value that will disallow any  operation  from
       within  hugin  as  to  force  the  user  to set this parameter. Without
       knowing this parameter, any work would be invalid, thats why  we  force
       such strict behaviour, sorry.

BUGS

       No  bugs known, if you find any, please send a bug report to me. I will
       try to fix it.

AUTHOR

       Sebastian Nowozin <nowozin at cs dot tu dash berlin dot de>

SEE ALSO

       autopano-sift(7), autopano-complete(1), generatekeys(1),  autopanog(1),
       showone(1), showtwo(1)