Update README.md

1 files changed, 212 insertions, 33 deletions

diff --git a/README.md b/README.md
index 6099395..385476b 100644
--- a/README.md
+++ b/README.md
@@ -1,33 +1,212 @@
-# gipfel-rs
-
-Rust port of [gipfel](https://git.flpsed.org/gipfel)'s computational core.
-
-- `crates/gipfel-core` — hills, panorama geometry, projections (maxima-generated
-  symbolic derivatives), pure-Rust Levenberg-Marquardt fit, `gipfel:` JPEG comment + EXIF I/O
-- `crates/gipfel-cli` — `export-position`, `export-hills`, `info`
-- `codegen/` — maxima scripts (`expr2rust.mac`) and `regen.sh`
-- `tests/` — C reference harnesses + golden files from the original C++ build
-
-```sh
-cargo test --lib --test golden     # unit + golden tests
-cargo run -p gipfel-cli -- info <img.jpg>
-```
-
-The Rust build has no native C dependencies. Regenerate goldens with
-`tests/gen_golden.sh` (needs the built C++ tree, which uses GSL; see
-`GIPFEL_SRC`/`GIPFEL_DATA` in the script).
-
-## gipfel-app (M2/M3)
-
-COSMIC desktop application: `cargo build --release -p gipfel-app` →
-`target/release/gipfel [image.jpg] [--data gipfel.dat]`.
-
-- Viewport: ctrl+wheel zoom (cursor-anchored), wheel/drag pan, fit/zoom buttons
-- Left-drag a flag to reposition (refits on release); middle-click or
-  double-click toggles a hill "known"; right-click → Find Peak / Hide-Unhide
-- Viewpoint / Find Peak pickers are searchable dialogs
-- Sidebar: compass dial, focal/pitch/roll/visibility/track sliders, viewpoint
-  lat/lon/height, distortion k0/k1/x0, projection, show-hidden
-- File menu: Open/Save (writes the `gipfel:` comment), Screen Dump (PNG/JPG
-  with markers burned in), Load Track (CSV: lat,lon,height rows)
-- Install `crates/gipfel-app/data/org.gipfel.App.desktop` per freedesktop
+gipfel
+======
+
+[homepage](http://www.flpsed.org/gipfel.html)
+
+Description
+-----------
+__gipfel__ helps to find the names of mountains or points of interest
+on a picture.
+It uses a database containing names and GPS data. With the given viewpoint
+(the point from which the picture was taken) and two known mountains
+on the picture, gipfel can compute all parameters needed to compute the
+positions of other mountains on the picture.
+gipfel can also be used to play around with the parameters manually.
+But it's pretty difficult to find the right parameters for a given
+picture manually.  
+You can think of gipfel as a georeferencing software for arbitrary images
+(not only satelite images or maps).  
+gipfel also has an image stitching mode, which allows to generate
+panorama images from multiple images that have been referenced with gipfel.
+The nice thing about image stitching is that it reuses the code that
+already exists for referencing images.  
+gipfel uses the non-linear
+[least squares method](http://en.wikipedia.org/wiki/Least_squares) to
+compute the viewing parameters from the given data points.
+
+![gipfel screenshot(file://gipfel_screenshot.png)
+
+Requirements
+------------
+* [cargo](https://github.com/rust-lang/cargo)
+* gipfel works on UNIX-like systems (e.g. Linux, *BSD and probably others)
+
+Installation
+------------
+COSMIC desktop application: `cargo build --release -p gipfel-app`.
+Then run it with `target/release/gipfel [image.jpg] [--data gipfel.dat]`.
+
+Running
+-------
+You should now see a window with controls on the left and the actual picture.
+Depending on whether gipfel could find localization data in the image metadata,
+you need to set the viewpoint from which the picture was taken. 
+Alternatively, you can enter the GPS coordinate of the viewpoint directly in
+the control window (hit <Enter> for every data field).  
+You can now use the controls in the control window to modify the view
+parameters.
+
+Play around with these parameters, until you see the names of 
+mountains, which you already recognize on the picture.
+Now middle-click on the small cross at the left of the name to mark it.
+It should turn red. Now you can drag it with the left mouse button pressed
+to the position of the mountain on the picture.
+If you have positioned at least two mountains all other mountains should
+move to their correct positions in the picture.
+You can try to set more than two mountains to ge a more accurate result.
+
+You may also want to have a look at the (outdated)
+(screen video)[http://www.flpsed.org/images/gipfel.avi]
+for an example session.
+
+Data File
+---------
+As stated before, gipfel needs GPS input data. The input data must be
+an ASCII file with one line per mountain / point of interest.
+Each line must contain the following values separated by a comma:
+
+	<SHORTNAME>,<NAME>,<DESCRIPTION>,<LATITUDE>,<LONGITUDE>,<HEIGHT>
+
+<SHORTNAME> and <DESCRIPTION> may be left empty.
+
+The following line is a valid example:
+	SMTSBG,Simetsberg,,47.56617,11.25358,1836
+
+Fortunately, there is a [great website](http://www.alpin-koordinaten.de),
+where you can download a suitable file containg quite a lot of data mostly 
+concerning the alps:
+Click on the "Suchen" button and the click on the diskette symbol below
+the first table then select "Fugawi 3 TXT" format and click on "Download".
+
+You can easily add your own entries to the data file or add them
+to the database at http://www.alpin-koordinaten.de.
+
+Thanks to the kind permission of
+[Jonathan de Ferranti](http://www.viewfinderpanoramas.org/) and the
+creators of http://www.alpin-koordinaten.de, the standard gipfel
+tarball includes a default datafile generated from these two sources.
+
+For the USA, you can download a data file
+from [USGS](http://geonames.usgs.gov/domestic/download_data.htm)
+The file can be transformed for gipfel with
+	awk 'BEGIN {FS="|"; OFS=","};
+	     $3 == "Summit" {print "usgs_" $1, $2,"" , $10, $11, $16};'
+
+GPS Tracks
+----------
+Once you have determined the right parameters using the procedure described
+above, you can load GPS tracks and display them on the picture. Use the
+File->Load Track menu item. GPS tracks should be in GPX format.
+GPS tracks are displayed with variable width depending on the distance 
+of the way points from the current view point and the scale value. 
+You can also modify the width using the "Track Width" slider.
+
+Loading and Saving Images
+-------------------------
+gipfel allows to save the image parameters in the comment section of 
+the JPEG image. Use the File->Save Image menu item. 
+Note, that in the saved image all previous JPEG comments are removed.
+If you open an image containing gipfel image parameters, they are 
+automatcally set.
+
+Hidden Object Detection
+-----------------------
+gipfel tries to identify objects in its database, that are hidden by others.
+This is done by assuming that every object/peak has the form of a cone 
+with a fixed steepness. If such imaginary cone would hide the view to a
+point in the database, gipfel marks it as hidden. Hidden objects are
+not shown by default, but you can enable the display of hidden objects using
+the Option->Show Hidden menu entry. Hidden objects and hidden GPS way points
+are displayed in blue.
+
+Refraction
+----------
+Refraction caused by temperature and density gardients in the atmosphere is
+taken into account according to the approximation described by
+[Tom Chester](http://tchester.org/sgm/analysis/peaks/refraction_calculation.html).
+under the assumption of a temperature change of 6.5C per 1000m and a
+temperature T0 at view point level of 10C.
+
+Exif Data
+---------
+gipfel tries to get useful information from the exif data of the
+input image. It uses the "Focal Length in 35mm Film" and the 
+"GPS Longitude", "GPS Latitude", and "GPS Height" parameters, if they
+exist.
+
+Lens Distortion
+---------------
+Typical lenses especially wide-angle lenses diverge from the optimal
+rectilinear projection.
+gipfel can partly correct the resulting errors.
+To this end gipfel uses a standard distortion model with three parameters 
+(k0, k1, and x0). Depending on these values, the distance d of an image
+point from the center is modified by (k0 * d + k1 * d ^ 2).
+x0 is the main point offset in X direction.  
+
+If you mark and position more than 3 mountains on an image and enable distortion fitting,
+gipfel tries to correct lens distortion.
+Once you have reasonable values for k0 and k1 for a special camera and
+focal length you can save the distortion profile (Distortion/Save Profile).
+Whenever you now open an image taken with this camera model and focal
+length, gipfel will use this distortion profile.
+Independent of the distortion profiles one can also modify the
+distortion parameters per image.
+Distortion correction is also used when stitching panorama images.
+
+Stitching Panorama Images
+-------------------------
+If you have multiple images from the same viewpoint referenced with gipfel
+you can stitch them together to form a panorama image.
+For stitching the input images must all have been correctly referenced
+with gipfel and saved (see "Loading and Saving Images").
+You can then call `gipfel stitch -t <outimg> <img1> <img2> ...`
+to save the result as TIFF image.
+To get multiple TIFF images as input for
+<http://enblend.sourceforge.net/>, call gipfel like this:
+`for i in *.jpg; do gipfel -s -b -t tiff/$i $i; done`
+
+The width and height of the result images can be adjusted with
+additional -w and -h options.
+You can use the -b switch to enable bicubic interpolation, which
+gives smoother results but is a bit slower.  
+
+gipfel simply scans all directions needed for the panorama and determines
+where these directions would end up on the various pictures. It can then
+record the corresponding color values from the input images.  
+
+In contrast to other stitching programs, the input images don't need to
+overlap.
+
+If you want to open a stitched image in gipfel to locate the mountains
+on it, don't forget to choose Panoramic Projection!
+
+Troubleshooting
+---------------
+* Obviously gipfel can only be as good as its input data. If there is no 
+  data about the mountains on your picture, you are out of luck...
+  But as the data file format is pretty simple and GPS receivers are common, 
+  you can build up your own datafile.
+* gipfel only works with full normal unmodified pictures taken with a 
+  non-distorting standard objektive. If you have a panorama picture, you
+  might want to try the "Panoramic Projection" support which 
+  imlements a cylindrical projection (see "Projection" menu).
+* I don't know, whether gipfel currently works correctly on pictures taken on
+  the southern hemisphere, but I would appreciate any feedback about it.
+
+Acknowledgements
+----------------
+Thanks to the guys from http://www.alpin-koordinaten.de for their public
+GPS database. 
+Also have look at their other [site](http://www.alpen-panoramen.de).
+In newer versions I use [maxima](http://maxima.sourceforge.net/) for
+symbolic computation and code generation.
+I also want to thank my brother Martin for his suggestions and the
+discussions.
+
+DISCLAIMER
+----------
+gipfel must __not__ be used for real navigation. You should not rely on the 
+results of gipfel.
+
+Johannes Hofmann, <Johannes.Hofmann@gmx.de>