doc/index.org

   1 #+TITLE:     Phoros
   2 #+AUTHOR:    Bert Burgemeister
   3 #+EMAIL:     trebbu@googlemail.com
   4 #+DESCRIPTION:
   5 #+KEYWORDS:
   6 #+LANGUAGE:  en
   7 #+OPTIONS:   H:3 num:nil toc:1 \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
   8 #+OPTIONS:   TeX:nil LaTeX:nil skip:nil d:nil todo:t pri:nil tags:not-in-toc
   9 #+OPTIONS:   author:t email:t creator:nil timestamp:t
  10 #+HTML_HEAD: <link rel="stylesheet" href="style.css" type="text/css"/>
  11 #+ATTR_HTML: alt="Phoros logo" height="50" style="padding-top:.5em;float:right"
  12   [[file:phoros-logo-plain.png]]
  13
  14 A Tool for Photogrammetric Road Survey
  15
  16 * Workflow
  17
  18   - Images and GPS data are acquired using a measuring vehicle.
  19     ([[http://tu-dresden.de/die_tu_dresden/fakultaeten/vkw/ivs/gsa/professur/ausstattung/messfahrzeug_uno][Here]]
  20     is a working example.)
  21
  22     Sequences of a few hundred images together with their trigger
  23     times are stored Huffman-encoded in files called =*.pictures=.
  24     GPS data is preprocessed into a table of ASCII text.  The format
  25     of both image and GPS files is not (yet) explained here.
  26
  27   - Cameras and GPS system need to be calibrated, which is not
  28     explained here.
  29
  30   - Calibration parameters are stored into the database using the
  31     [[Command Line Interface]] (There, cf.
  32     =Camera Hardware Parameters= through
  33     =Camera Calibration Parameters=.)
  34
  35   - GPS data and image information are fed into the database using
  36     option =--store-images-and-points= of the [[Command Line Interface]].
  37
  38   - Presentation project users use the web interface to point in a map
  39     at a point of interest and are shown a couple of relevant images.
  40     In these images they point at features of interest the coordinates
  41     of which can be stored into the database.  (Storage not yet
  42     implemented; coordinates are just shown.)
  43
  44 * Command Line Interface
  45
  46   The command line interface is used to
  47
  48   - initialize a fresh PostgreSQL database
  49     (=./phoros --create-sys-tables ...=),
  50
  51   - set up and manage acquisition projects
  52     (=./phoros --create-acquisition-project ...=),
  53
  54   - store camera calibration parameters (=--store-camera-hardware=,
  55     =--store-device-stage-of-life=, =--store-camera-calibration= etc.),
  56
  57   - store measurement data, i.e., images and GPS positions
  58     (=./phoros --store-images-and-points ...=),
  59
  60   - manage presentation projects and presentation project users
  61     (=--create-presentation-project=, =--create-user= etc.),
  62
  63   - start Phoros as a presentation server (a web server presenting
  64     measurement data to presentation project users) by
  65     =./phoros --server ...=.
  66
  67   #+BEGIN_SRC sh
  68   $ ./phoros --help
  69   #+END_SRC
  70   emits a rather comprehensive [[file:phoros--help.org][help message]].
  71
  72 * Web Interface
  73
  74   Once images, calibration data and definitions of users and projects
  75   have been stored using the [[Command Line Interface]], Phoros can be
  76   started as a web server:
  77 #+BEGIN_SRC sh
  78 $ ./phoros --server \
  79 >          --common-root=/some_path/where_i_put/my_raw_images/ \
  80 >          --host=my_server --port=5432 --database=my_projects \
  81 >          --user=database_admin --password=SeCrEt
  82 #+END_SRC
  83   A user can than point their browser at Phoros's URL.  Example:
  84   =http://localhost:8080/phoros/beautiful-cities= connects to
  85   presentation project =beautiful-cities= (and asks for username and
  86   password).
  87
  88 ** Choose a point from the map
  89    In the map, small yellow circles represent points of view of the
  90    available images.  Pointing into an area of interest has Phoros
  91    select and display a few[fn:: The number of images can be specified
  92    during server start. Example: =phoros --server --images=N ...=]
  93    images containing the point clicked, which on the
  94    streetmap is represented by the dark blue Phoros logo.
  95
  96    #+ATTR_HTML: style="border:2px solid darkgrey"
  97    [[file:phoros-12.8.1.png]]
  98
  99 ** Point into first image
 100    After zooming into a first image and selecting a feature of
 101    interest, [[http://en.wikipedia.org/wiki/Epipolar_line#Epipolar_line][epipolar lines]] appear in the other images which may be
 102    helpful in recognising the selected feature there.
 103
 104    Points selected in images are represented by large yellow circles.
 105
 106 ** Point into second image
 107    Zooming in and selecting the same feature in a second image
 108    triggers calculation of the estimated global position.  The
 109    estimated position is now shown as a cyan circle in all images and
 110    in the map.  Neither estimated position accuracy nor pointing
 111    precision are bounded by pixel size.
 112
 113 ** Improve accuracy
 114    Zooming in and pointing at the feature in some (or all) of the
 115    remaining images improves accuracy.
 116
 117 ** Store point
 118    Finishing this point means storing it in a dedicated user point
 119    table.
 120
 121 * Deployment
 122 ** Download
 123
 124   - Browse Phoros source code via gitweb at [[http://github.com/trebb/phoros][Github]].
 125
 126   - Browse source code of [[mailto:Steffen.Scheller.home@gmail.com][Steffen Scheller]]'s [[http://github.com/trebb/phoml][PhoML]] library, which is
 127     needed by Phoros.
 128
 129   - Get everything:
 130     #+BEGIN_SRC sh
 131     $ git clone git://github.com:trebb/phoros.git
 132     $ # or: git clone https://github.com/trebb/phoros.git
 133     $ cd phoros
 134     $ git submodule init
 135     $ git submodule update
 136     #+END_SRC
 137
 138     The build process isn't perfect yet.  You'll (probably) need an
 139     x86-64 Debian system with [[http://beta.quicklisp.org][Quicklisp]] installed on top of [[http://www.sbcl.org][SBCL]].
 140
 141 ** Debian Installation Walk-Through
 142
 143    - Install Debian; choose standard system tools and (probably) SSH server.
 144
 145    - Install Debian packages
 146      ed,
 147      emacs,
 148      fonts-sil-gentium,
 149      g++,
 150      git,
 151      icoutils,
 152      imagemagick,
 153      proj-bin,
 154      sbcl,
 155      sbcl-source,
 156      slime,
 157      swig.
 158
 159    - Install (as a non-root user) quicklisp:
 160      #+BEGIN_SRC sh
 161      $ wget https://beta.quicklisp.org/quicklisp.lisp
 162      $ sbcl --load quicklisp.lisp
 163      #+END_SRC
 164      In SBCL, type
 165      #+BEGIN_SRC lisp
 166      (quicklisp-quickstart:install)
 167      (ql:add-to-init-file)
 168      (quit)
 169      #+END_SRC
 170
 171    - Build and install Phoros:
 172      #+BEGIN_SRC sh
 173      $ git clone ... #(see above)
 174      $ cd phoros
 175      $ git submodule init
 176      $ git submodule update
 177      $ make bin-tarball
 178      $ mkdir ~/phoros-workspace
 179      $ cp ~/phoros/phoros_VERSION_x86_64.tar.gz ~/phoros-workspace/
 180      $ cd ~/phoros-workspace
 181      $ tar -xzf phoros_VERSION_x86_64.tar.gz
 182      $ ln -s phoros_VERSION_x86_64 phoros
 183      $ cd ~/phoros-workspace/phoros
 184      $ ./phoros --check-dependencies
 185      $ ./phoros --check-db --host=DB_HOST --user=DB_USER --password=SECRET --database=PHOROS_WORKSPACE_DB --aux-host=DB_HOST --aux-user=DB_USER --aux-password=SECRET --aux-database=PHOROS_WORKSPACE_DB
 186      $ ./phoros --create-sys-tables --host=DB_HOST --user=DB_USER --password=SECRET --database=PHOROS_WORKSPACE_DB
 187      #+END_SRC
 188
 189    - Peruse the [[file:deployment.org][example scripts]] and the [[file:phoros--help.org][help message]] to learn about Phoros administration.
 190
 191    - Building fasttrack:
 192      Install Debian package libmagickwand-dev
 193      #+BEGIN_SRC sh
 194      $ cd ~/quicklisp/local-projects
 195      $ git clone git://github.com/TBRSS/lisp-magick-wand
 196      #+END_SRC
 197      In lisp-magick-wand/base.lisp change
 198      #+BEGIN_SRC lisp
 199      (:unix (:or "libMagickWand.so" "libWand.so.9" "libWand.so"))
 200      #+END_SRC
 201      into
 202      #+BEGIN_SRC lisp
 203      (:unix (:or "libMagickWand-6.Q16.so" "libMagickWand.so" "libWand.so.9" "libWand.so"))
 204      #+END_SRC
 205      #+BEGIN_SRC sh
 206      $ make fasttrack
 207      #+END_SRC
 208
 209    - For use with firefox from fasttrack, set in about:config
 210      browser.link.open_newwindow.override.external to 1.
 211 * Licence
 212
 213   PHOROS -- Photogrammetric Road Survey
 214
 215   Copyright (C) 2010, 2011, 2012, 2015 [[mailto:Bert Burgemeister <trebbu@googlemail.com>][Bert Burgemeister]]
 216
 217   This program is free software; you can redistribute it and/or modify
 218   it under the terms of the GNU General Public License as published by
 219   the Free Software Foundation; either [[http://www.gnu.org/licenses/gpl-2.0.html][version 2 of the License]], or
 220   (at your option) any later version.
 221
 222   This program is distributed in the hope that it will be useful, but
 223   WITHOUT ANY WARRANTY; without even the implied warranty of
 224   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 225   General Public License for more details.
 226
 227   You should have received a copy of the GNU General Public License
 228   along with this program; if not, write to the Free Software
 229   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 230   02110-1301 USA.
 231
 232 * Acknowledgements
 233
 234   - Phoros is implemented using [[http://sbcl.org][Steel Bank Common Lisp]], a Common Lisp
 235     implementation.
 236
 237   - Communication with [[http://postgresql.org][PostgreSQL]] is provided by [[http://marijnhaverbeke.nl/postmodern/][Postmodern]].
 238
 239   - The presentation server is based on [[http://weitz.de/hunchentoot][Hunchentoot]].
 240
 241   - Almost everything visible in the web browser looks as it does
 242     thanks to the [[http://openlayers.org][OpenLayers]] library, interfaced by [[http://common-lisp.net/project/parenscript/][Parenscript]] and
 243     [[http://common-lisp.net/project/cl-json/][CL-JSON]].
 244
 245   - Without [[mailto:Steffen.Scheller.home@gmail.com][Steffen Scheller]]'s photogrammetric library [[http://github.com/trebb/phoml][PhoML]] Phoros's
 246     presentation server couldn't do much beyond displaying
 247     geolocated images.
 248
 249   - Once decoded, images are turned into something a web browser can
 250     handle by [[http://www.xach.com/lisp/zpng/][ZPNG]].
 251
 252   - Leap second information is taken from the [[http://hpiers.obspm.fr/eop-pc][Earth Orientation Center]].
 253
 254   - [[http://www.openstreetmap.org][OpenStreetMap]] provides the map.  (Other map services can be used
 255     as well, though.)