FIXME: need to update this page.  In particular:
  * autopanoaj is no longer used


====== Prereqs ======

===== Platform =====

Only supported under Linux (tested under Ubuntu 14).  If you find minor tweaks to make it work with others (ie Windows), I'll take them.  But I'm not interested in a large rewrite


===== Software =====

Core required:
  * Python 2.7 (or at least that's what I use)

Stitching:
  * ImageMagik


===== Installing via github =====

For Ubuntu:
  - sudo apt-get install -y git hugin
  - cd ~
  - git clone https://github.com/JohnDMcMaster/pr0ntools.git
  - export PYTHONPATH=$PYTHONPATH:~/pr0ntools/pr0ntools
  - export PATH=$PATH:~/pr0ntools/stitch
  - alias pr0nstitch=pr0nstitch.py
  - alias pr0npto=pr0npto.py
  - alias pr0nhugin=pr0nhugin.py
  - alias pr0nauto=pr0nauto.py


===== Installing via pip =====

Probably too outdated to be useful.  Don't use


===== Assumptions and notes =====

Although these tools are meant for very large stitches, this tutorial uses a small project.  Use this to get familiar with the workflow to avoid (time) costly mistakes in large stitches.

"$" indicates a command to execute.  For example "$ ls" means type ls followed by enter in the terminal


====== Quickstart ======

Do:
  - $ Make sure you already setup the tools as indicated above
  - $ cd ~
  - Get test data
    - $ wget https://siliconpr0n.org/map/ad/ad534/ad_ad534_mz_mit20x_raw.tar.bz2
    - $ tar -xf ad_ad534_mz_mit20x_raw.tar.bz2
    - $ cd ad_ad534_mz_mit20x_raw.
  - $ pr0nauto
  - Hugin GUI
    - GUI should open on a special reduced project (center will be missing)
    - Crop and rotate to your desire
    - TODO: add additional details how to do this
    - TODO: fix bug / add note about bad pr0nauto
  - $ pr0nts
  - Directory outputs
    * single: a .jpg with of the entire ROI selected in Hugin
    * st: "supertiles", one more intermediate partial .jpgs.  In this example there will probably be only one
    * out: Google map tiles that can be ingested by pr0nmap


====== Step 1: acquire images ======

Take images with roughly 1/3 overlap to each neighbor.  Tag them with x/y or r/c in the file names so that they can be used in positioning heuristics.  

Example file name: r0012_c0311.jpg

It shouldn't matter the order or if you use any 0 padding.  I generate these using pr0ncnc which could probably be adapted to your system but as of now is fairly specific to mine.  I did convert it from g-code generation to live runs over USB without too much effort so someone else's system probably wouldn't be too bad.  And the g-code generator probably still works if you can use that.

====== Step 2: generate features ======

cd into the directory with your images

Execute a command like: pr0nstitch *.jpg out.pto.  This will take some time but should give you a progress indicator of which match its on.  

When its done you will get a file called stitch-errors.json.  Look through it for images that couldn't be matched.  If there are any that have 0 matches you should probably patch them up by hand by loading the project into Hugin


====== Step 3: optimize ======

BUG: you must first open and it resave it in Hugin for PToptimizer to take it.  I haven't investigated why this is yet.  As a workaround use pr0npto --hugin out.pto to do this from the command line

Execute something like:

pr0npto --optimize out.pto

This may take a while but you should get occasional progress indicators.  When its done I recommend you center it using pr0npto --center out.pto

====== Step 4: Crop in Hugin ======

I might eventually automate this but for now things have to be done manually.  Open it Hugin and do the following:
  * Calculate optimal field of view.  This will give a reasonable baseline when you open it but probably won't be final
  * Open GL image preview.  This may take a long time but you should see each image loading as it goes along
  * Adjust the field of view as needed so that the entire pano is in view but try to still keep it as small as possible
  * Go to the crop tab and crop as needed
  * Save and exit

====== Step 5: stitch ======

You have several options at this point:
  * Stitch in Hugin using either its normal or batch option
  * Stitch through command line using Hugins makefile.  I tend to prefer this over the first since I can run it remotely and its easier to track
  * Stitch to tiles using pr0nts.  This is the recommended option for large projects since it avoids creating large intermediate images

Execute "pr0nts out.pto".  A folder called out will be created with the tiles.  This may take a very long time.  There are a lot of options on this tool so try --help and read over them if you need to weak things

You should use the maximum amount of memory you can to create the largest supertile possible.  I will eventually add an optimize option where it will calculate the best supertile scheme based on your machine's memory.


====== Step 6: create map ======

Now that you have tiles you can turn them into a map.  Execute pr0nmap out and it should create a dir called "map" that has index.html an subdirectories with tiles.  Try its help options to see what else it offers.

This should be a reasonably quick operation and will get much faster at each successive zoom level as it creates the next generation of tiles.  It only loads on 4 tiles at a time so this should not take a lot of memory.


====== Step 7: finishing up ======

Open index.html and you should see your chip.  If at the highest zoom level you aren't really getting anything over a previous level consider deleting all of the tiles in that directory and lowering the maxZoom parameter in index.html