Silicon Pr0n

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
The goal of this tool is to be able to stitch large panoramas easier on machines with fewer resources than may be desirable.  Instead of outputting a single large image like a standard stitch would do this tool generates a folder full of tiles.  These can then be processed into a Google maps type application. 

There are two modes:
  * Single: cut up a single input image
  * Project: 

====== Input files ======

I think there is an artificial requirement that the input images be tagged with row and col information (ex: y0123_x031.jpg).  I believe the stitcher either doesn't use this information (it relies on nona to do the clipping) or could easily be worked around as a slightly less optimized version.  If you are interested in using this tool but this is in your way talk to me and I can probably remove this requirement without too much effort.

====== Configuration ======

I have some limited configuration file support.  In particular you can have a JSON file called ~/.pr0nrc that can look like this:

    {
        "enblend": {
            "opts":"-m 10240"
        }
    }

That is you can pass in arbitrary additional options to enblend.  In the above example I do this to increase the cache size to 10 GB on my desktop which can afford that sort of memory allocation.

====== Usage ======

  usage: pr0nts [-h] [--stw SUPER_TW] [--sth SUPER_TH] [--force] [--merge]
              [--out-ext OUT_EXTENSION] [--full] [--st-xstep SUPER_T_XSTEP]
              [--st-ystep SUPER_T_YSTEP] [--clip-width CLIP_WIDTH]
              [--clip-height CLIP_HEIGHT] [--ignore-errors]
              pto project

  create tiles from unstitched images

  positional arguments:
    pto project           pto project

  optional arguments:
    -h, --help            show this help message and exit
    --stw SUPER_TW        Supertile width
    --sth SUPER_TH        Supertile height
    --force               Force by replacing old files
    --merge               Don't delete anything and only generate things missing
    --out-ext OUT_EXTENSION
                          Select output image extension (and type), .jpg, .png,
                          .tif, etc
    --full                use only 1 supertile
    --st-xstep SUPER_T_XSTEP
                          Supertile x step (advanced)
    --st-ystep SUPER_T_YSTEP
                          Supertile y step (advanced)
    --clip-width CLIP_WIDTH
                          x clip (advanced)
    --clip-height CLIP_HEIGHT
                          y clip (advanced)
    --ignore-errors       skip broken tile stitches (advanced)


====== Choosing optimial supertile size ======

The ideal supertile is the entire output panorama.  That is you stich a single image from all of the source images and then chop it up.  Unfortunately, this image may be too big to fit into your system or at least force you into swapping and result in abysmal performance.

I'd like to add an option that tries to optimize based on how much memory you feed it but nothing like that exists as of today.

On my production machine I have 12 GB of memory.  2 GB is plenty fine to run the system so I allocate 10 GB for stitching.  A 6 X 6 3264 X 2448 image takes up 90% of 12 GB or 9.6 GB on my system.  However, its important to generate as few supertiles as possible so yo might be better off sacrificing width for high or vice versa, especially if you have an oddly shaped image.  Take advantage of the pre-stitch dry run to play around with the image dimensions to cut down on stitching type.  Even by guess and check you should be able to cut significant time off of the stitch if you are creating an extra supertile row or col and could slightly trim it.

====== Examples ======

===== Simple =====

pr0nts out.pto

Pick some halfway reasonable defaults (that may still need fiddling) and output tiles to the directory "out" (or whatever $X in $X.pto is).  If the directory already exists an error will be thrown.

===== Advanced =====

pr0nts --clip-width 3264 --clip-height 2448 --stw=$[3264 * 5] --sth=$[2448 * 6] out.pto --merge --ignore-errors

Note my camera takes 3264 X 2448 images.  Don't stitch 3264 x units on each side overlapping another image and 2448 in the y direction.  Supertiles should be 16320 X 14688 pixels.  Use out.pto to determine stitch parameters and merge with the existing output.  If a command fails skip that supertile and try the next.  Note that the supertile dimensions don't have anything to do with the input image dimensions, its just a good heuristic that's easy to visualize.  In practice you should be able to fit quite a few more images in that space than raw image size due to overlap.


====== Symptoms and fixes ======

===== Garbled tiles =====

{{gallery>:pr0ntools:stitch:poor_opt.png?200}}

Chances are your project is poorly optimized.  You should be able to get an RMS error of < 5 without too much trouble and for good results it should be < 1.  In the above example there are two errors: tiles don't line up and seams appear within tiles.  The second occurs because images are conflicting and enblend can't chose a good seam.  The first error occurs because these poor seems may be chosen differently between supertiles.  You might be able to mitigate this by choosing a larger clip size but you should really fix your optimization.


===== Uneven adjacent tile brightness =====

{{gallery>:pr0ntools:stitch:photometric_error.png}}

Your source images have uneven brightness.  This can happen using auto-brightness, lamp misalignment, an uneven sample, or because there is a brightness gradient from using polarized light on non-strain-free objectives.  Try increasing the clip width/height as it will force a large area to be melded together before creating a tile.


===== Enblend fails =====

Usually enblend will fail from out of memory.  Try reducing the supertile size.  nona only uses as much memory as your largest single image so it shouldn't be a problem.


====== Tile size ======

I chose 250x250 because that's what Google maps default is.  I think I put in command line to change that as needed but its not well tested.


====== BBB/machinekit ======

<code>
echo >>~/.ssh/config <<EOF

Host mk
User machinekit
EOF

sudo tee -a /etc/hosts <<EOF
192.168.7.2     mk
EOF

# TODO: how to set static network config auto?
# Need 192.168.7.1 / 30 IIRC
</code>