Phoros
Table of Contents
A Tool for Photogrammetric Road Survey
Help Message
(Output of ./phoros --help)
Usage: phoros [-h] [OPTIONS]
Phoros (http://phoros.boundp.org) is a tool for photogrammetric road survey. It
stores data in a PostgreSQL database and then makes it available over a web
interface.
Some options have a corresponding environment variable. Phoros will set
environment variables from definitions found in file
<phoros-invocation-dir>/.phoros or, if that doesn't exist, in file ~/.phoros.
Options specified on the command line take precedence over any environment
variables. Pre-existing environment variables take precendence over definitions
found in any .phoros files.
Config file syntax: one option per line; leading or trailing spaces are ignored;
anything not beginning with PHOROS_ is ignored.
-h, --help[=FORMAT]
Print help in different formats [long|short] and exit.
Fallback: long
--licence
Print licence boilerplate and exit.
--license
Same as --licence
--version[=FORMAT]
Print different amounts [minimal|all] of version information and exit.
In a version string A.B.C, changes in A denote incompatible changes
in data; changes in B mean user-visible changes in feature set.
Fallback: minimal
General Options:
--verbose=STR
Change behaviour, mainly for debugging, as specified in the form of
<verbosity-topic>:<verbosity-level>. Repeat if necessary.
render-footprints:1 - display image footprints on http client;
suppress-preemptive-caching:1 - don't stuff browser cache with lots
of images around map cursor;
log-sql:1 - log SQL activity;
postgresql-warnings:1 - show PostgreSQL warnings;
log-error-backtraces:1 - log http server error backtraces;
use-multi-file-openlayers:1 - use multi-file version of OpenLayers;
pretty-javascript:1 - send nicely formatted JavaScript;
show-server-errors:1 - send HTTP server error messages to client;
no-daemon:1 - run HTTP server in foreground;
swank-port:<port> - start swank server listening on <port>, offering
interactive debugging of the running Lisp process. Use slime-connect
from inside Emacs SLIME to connect locally to <port>; or establish an
ssh tunnel on a remote client, "ssh -L <local-port>:127.0.0.1:<port>
user@phoros-host", and slime-connect on the remote client to
<local-port>.
--umask=OCTAL_NUMBER
File permissions mask applied when Phoros creates files and
directories.
Default: 002
Environment: PHOROS_UMASK
--log-dir=PATH
Where to put the log files. Created if necessary; should end with a
slash.
Default: log.d/
Environment: PHOROS_LOG_DIR
--check-db
Check connection to databases (including auxiliary if applicable) and
exit.
--check-dependencies
Check presence of dependencies on local system and exit.
--nuke-all-tables
Ask for confirmation, then delete anything in database and exit.
--create-sys-tables
Ask for confirmation, then create in database a set of sys-* tables
(tables shared between all projects). The database should probably be
empty before you try this.
Database Connection:
Necessary for most operations.
-H, --host=NAME
Database server.
Default: localhost
Environment: PHOROS_HOST
-P, --port=INT
Port on database server.
Default: 5432
Environment: PHOROS_PORT
-D, --database=NAME
Name of database.
Default: phoros
Environment: PHOROS_DATABASE
-U, --user=NAME
Database user.
Environment: PHOROS_USER
-W, --password=PWD
Database user's password.
Environment: PHOROS_PASSWORD
--use-ssl=MODE
Use SSL in database connection. [yes|no|try]
Default: no
Environment: PHOROS_USE_SSL
Auxiliary Database Connection:
Connection parameters to the database containing auxiliary data. Only
needed for definition (--create-aux-view) and use (--server) of
auxiliary data.
--aux-host=NAME
Auxiliary database server.
Default: localhost
Environment: PHOROS_AUX_HOST
--aux-port=INT
Port on auxiliary database server.
Default: 5432
Environment: PHOROS_AUX_PORT
--aux-database=NAME
Name of auxiliary database.
Environment: PHOROS_AUX_DATABASE
--aux-user=NAME
Auxiliary database user.
Environment: PHOROS_AUX_USER
--aux-password=PWD
Auxiliary database user's password.
Environment: PHOROS_AUX_PASSWORD
--aux-use-ssl=MODE
Use SSL in auxiliary database connection. [yes|no|try]
Default: no
Environment: PHOROS_AUX_USE_SSL
Examine .pictures File:
Useful primarily for debugging purposes.
--get-image
Get a single image from a .pictures file, print its trigger-time to
stdout, and exit.
--count=INT
Image number in .pictures file.
Default: 0
--byte-position=INT
Byte position of image in .pictures file.
--in=PATH
Path to .pictures file.
--out=PATH
Path to output .png file.
Default: phoros-get-image.png
--bayer-pattern=STR
The first pixels of the first row. Each pixel is to be interpreted as
RGB hex string. Example: use #ff0000,#00ff00 if the first pixels in
topmost row are red, green.
Default: #ff0000,#00ff00
Calibration Data:
Camera Hardware Parameters:
These do not include information on lenses or mounting.
--store-camera-hardware
Put new camera-hardware data into the database; print
camera-hardware-id to stdout.
--sensor-width-pix=INT
Width of camera sensor.
--sensor-height-pix=INT
Height of camera sensor.
--pix-size=NUM
Camera pixel size in millimetres (float).
--channels=INT
Number of color channels
--pix-depth=INT
Greatest possible pixel value.
Default: 255
--color-raiser=STR
Multipliers for the individual color components. Example: 1.2,1,.8
multiplies red by 1.2 and blue by 0.8.
Default: 1,1,1
--bayer-pattern=STR
The first pixels of the first row. Each pixel is to be interpreted as
RGB hex string. Example: use #ff0000,#00ff00 if the first pixels in
topmost row are red, green.
Default: #ff0000,#00ff00
--serial-number=STR
Serial number.
Default:
--description=STR
Description of camera.
Default:
--try-overwrite=yes/no
Overwrite matching record if any.
Default: yes
Lens Parameters:
Stored primarily for human consumption; not used in photogrammetric
calculations.
--store-lens
Put new lens data into the database; print lens-id to stdout.
--c=NUM
Focal length.
--serial-number=STR
Serial number.
Default:
--description=STR
Description of camera.
Default:
--try-overwrite=yes/no
Overwrite matching record if any.
Default: yes
Generic Device Definition:
Basically, this is a particular camera fitted with a particular lens.
--store-generic-device
Put a newly defined generic-device into the database; print
generic-device-id to stdout.
--camera-hardware-id=ID
Numeric camera hardware ID in database.
--lens-id=ID
Numeric lens ID in database.
Device Stage-Of-Life Definition:
A stage-of-life of a generic device is a possibly unfinished period of
time during which the mounting constellation of the generic device
remains unchanged.
--store-device-stage-of-life
Put a newly defined device-stage-of-life into the database; print
device-stage-of-life-id to stdout.
--recorded-device-id=STR
Device id stored next to the measuring data.
--event-number=STR
GPS event that triggers this generic device.
--generic-device-id=ID
Numeric generic-device id in database.
--vehicle-name=STR
Descriptive name of vehicle.
--casing-name=STR
Descriptive name of device casing.
Default:
--computer-name=STR
Name of the recording device.
Default:
--computer-interface-name=STR
Interface at device.
Default:
--mounting-date=STR
Time this device constellation became effective. Format:
"2010-11-19T13:49+01".
--unmounting-date=STR
Time this device constellation ceased to be effective. Format:
"2010-11-19T17:02+01".
Default: :null
Put An End To A Device's Stage-Of-Life:
This should be done after any event that renders any portion of the
calibration data invalid. E.g.: accidental change of mounting
constellation.
--store-device-stage-of-life-end
Put an end date to a device-stage-of-life in the database; print
device-stage-of-life-id to stdout.
--device-stage-of-life-id=ID
ID of the device-stage-of-life.
--unmounting-date=STR
Time this device constellation ceased to be effective. Format:
"2010-11-19T17:02+01".
Default: :null
Camera Calibration Parameters:
--store-camera-calibration
Put new camera-calibration into the database; print generic-device-id
and calibration date to stdout.
--device-stage-of-life-id=ID
ID of the device-stage-of-life.
--date=STR
Date of calibration. Format: "2010-11-19T13:49+01".
--person=STR
Person who did the calibration.
--main-description=STR
Regarding this entire set of calibration data
--usable[=yes/no]
Set to no to just display images and inhibit photogrammetric
calculations.
Fallback: yes
Default: yes
--debug[=yes/no]
If yes: not for production use; may be altered or deleted at any time.
Fallback: yes
Default: no
--photogrammetry-version=STR
Software version used to create this data.
--mounting-angle=OBJ
Head up = 0; right ear up = 90; left ear up = -90; head down = 180.
--inner-orientation-description=STR
Comments regarding inner orientation calibration.
Default:
--c=NUM
Focal length.
--xh=NUM
Inner orientation: principal point displacement.
--yh=NUM
Inner orientation: principal point displacement.
--a1=NUM
Inner orientation: radial distortion.
--a2=NUM
Inner orientation: radial distortion.
--a3=NUM
Inner orientation: radial distortion.
--b1=NUM
Inner orientation: asymmetric and tangential distortion.
--b2=NUM
Inner orientation: asymmetric and tangential distortion.
--c1=NUM
Inner orientation: affinity and shear distortion.
--c2=NUM
Inner orientation: affinity and shear distortion.
--r0=NUM
Inner orientation.
--outer-orientation-description=STR
Comments regarding outer orientation calibration.
Default:
--dx=NUM
Outer orientation; in metres.
--dy=NUM
Outer orientation; in metres.
--dz=NUM
Outer orientation; in metres.
--omega=NUM
Outer orientation.
--phi=NUM
Outer orientation.
--kappa=NUM
Outer orientation.
--boresight-description=STR
Comments regarding boresight alignment calibration.
Default:
--b-dx=NUM
Boresight alignment.
--b-dy=NUM
Boresight alignment.
--b-dz=NUM
Boresight alignment.
--b-ddx=NUM
Boresight alignment.
--b-ddy=NUM
Boresight alignment.
--b-ddz=NUM
Boresight alignment.
--b-rotx=NUM
Boresight alignment.
--b-roty=NUM
Boresight alignment.
--b-rotz=NUM
Boresight alignment.
--b-drotx=NUM
Boresight alignment.
--b-droty=NUM
Boresight alignment.
--b-drotz=NUM
Boresight alignment.
--nx=NUM
X component of unit vector of vehicle ground plane.
--ny=NUM
Y component of unit vector of vehicle ground plane.
--nz=NUM
Z component of unit vector of vehicle ground plane.
--d=OBJ
Distance of vehicle ground plane.
Manage Acquisition Projects:
An acquisition project is a set of measurements which share a set of
data tables and views named like dat-<acquisition-project-name>-point,
dat-<acquisition-project-name>-image,
dat-<acquisition-project-name>-aggregate.
--create-acquisition-project=NAME
Create a fresh set of canonically named data tables. NAME is the
acquisition project name. It will be stored in table
sys-acquisition-project, field common-table-name, and used as a common
part of the data table names.
--delete-acquisition-project=NAME
Ask for confirmation, then delete acquisition project NAME and all its
measurements.
--delete-measurement=INT
Delete a measurement by its ID.
--list-acquisition-project[=NAME]
List measurements of one acquisition project if its name is specified,
or of all acquisition projects otherwise.
Fallback: *
Store Measure Data:
-s, --store-images-and-points=NAME
Link images to GPS points; store both into their respective DB tables.
Images become linked to GPS points when their respective times differ
by less than epsilon seconds, and when the respective events match.
The string argument is the acquisition project name.
-d, --directory=PATH
Directory containing one set of measuring data.
-r, --common-root=PATH
The root part of directory that is equal for all pojects. TODO: come
up with some sensible default.
Environment: PHOROS_COMMON_ROOT
--epsilon=NUM
Difference in seconds below which two timestamps are considered equal.
Default: 0.001
--aggregate-events[=yes/no]
Put all GPS points in one bucket, disregarding any event numbers. Use
this if you have morons setting up your generic-device. Hundreds of
orphaned images may indicate this is the case.
Fallback: yes
Default: no
--insert-footprints=NAME
Update image footprints (the area on the ground that is most probably
covered by the respective image) for acquisition project NAME.
Become An HTTP Presentation Server:
Phoros is a Web server in its own right, but you can also put it
behind a proxy server to make it part of a larger Web site. E.g., for
Apache, load module proxy_http and use this configuration:
ProxyPass /phoros http://127.0.0.1:8080/phoros
ProxyPassReverse /phoros http://127.0.0.1:8080/phoros
--server
Start HTTP presentation server as a daemon. Entry URIs are
http://<host>:<port>/phoros/<presentation-project>. Asynchronously
update lacking image footprints (which should have been done already
using --insert-footprints).
--proxy-root=STR
First directory element of the server URL. Must correspond to the
proxy configuration if Phoros is hidden behind a proxy.
Default: phoros
--address=STR
Address (of local machine) server is to listen on. Default is
listening on all available addresses.
Default: *
--http-port=INT
Port the presentation server listens on.
Default: 8080
-r, --common-root=PATH
The root part of directory that is equal for all pojects. TODO: come
up with some sensible default.
Environment: PHOROS_COMMON_ROOT
--images=INT
Number of photos displayed on HTTP client.
Default: 4
--aux-numeric-label=STR
HTML label for an element of auxiliary numeric data. Repeat if
necessary. The succession of labels should match the auxiliary data
(defined by --numeric-column) of all presentation projects served by
this server instance.
--aux-text-label=STR
HTML label for an element of auxiliary text data. Repeat if
necessary. The succession of labels should match the auxiliary data
(defined by --text-column) of all presentation projects served by this
server instance.
--login-intro=STR
Text to be shown below the login form. Use repeatedly to divide text
into paragraphs. You can use HTML markup as long as it is legal
inside <p>...</p>
--pid-file=PATH
Where to put Phoros' PID when run as a daemon.
Default: phoros.pid
Environment: PHOROS_PID_FILE
Manage Presentation Projects:
A presentation project is a set of measurements that can be visited
under a dedicated URL
(http://<host>:<port>/phoros/<presentation-project>). Its extent may
or may not be equal to the extent of an acquisition project.
Presentation projects have a table of user points and a table of user
lines. The former is associated with a trigger which may be defined
to induce writing into the latter.
--create-presentation-project=NAME
Create a fresh presentation project NAME which is to expose a set of
measurements to certain users.
--delete-presentation-project=NAME
Ask for confirmation, then delete the presentation project including
its table of user-generated points.
--list-presentation-project[=NAME]
List one presentation project if specified, or all presentation
projects if not.
Fallback: *
--add-to-presentation-project=NAME
Add to presentation project NAME either certain measurements or all
measurements currently in a certain acquisition project.
--remove-from-presentation-project=NAME
Remove from presentation project NAME either certain measurements or
all measurements currently in a certain acquisition project.
--measurement-id=ID
One measurement-id to add or remove. Repeat if necessary.
--acquisition-project=NAME
The acquisition project whose measurements are to add or remove.
--redefine-trigger-function=NAME
Change body of the trigger function that is fired on changes to the
user point table connected to presentation project NAME.
--plpgsql-body=PATH
File containing the body of a PL/pgSQL trigger function. Any
ocurrence of the strings ~0@*~A and ~1@*~A will be replaced by the
name of the user point table/of the user line table respectively.
Omit this option to reset that function to just emit a notice.
Define Selectable Attributes For Images:
HTTP client users can select classes of images defined here.
Attributes are defined as PostgreSQL expressions and may use the
following column names:
recorded_device_id, device_stage_of_life_id, generic_device_id,
random, presentation_project_id, directory, measurement_id, filename,
byte_position, point_id, footprint, footprint_device_stage_of_life_id,
trigger_time, longitude, latitude, ellipsoid_height, cartesian_system,
east_sd, north_sd, height_sd, roll, pitch, heading, roll_sd, pitch_sd,
heading_sd, usable, sensor_width_pix, sensor_height_pix, pix_size,
bayer_pattern, color_raiser, mounting_angle, dx, dy, dz, omega, phi,
kappa, c, xh, yh, a1, a2, a3, b1, b2, c1, c2, r0, b_dx, b_dy, b_dz,
b_rotx, b_roty, b_rotz, b_ddx, b_ddy, b_ddz, b_drotx, b_droty,
b_drotz, nx, ny, nz, d.
Additionally, each of the column names can be prefixed by "first_" in
order to refer to image data of the first image. (Example:
"measurement_id = first_measurement_id" only displays images with
equal measurement_id.)
--create-image-attribute=NAME
Store, for presentation project NAME, a PostgreSQL expression an HTTP
client user can use to select some subset of the images available.
--delete-image-attribute=NAME
Delete presentation project NAME an image restriction identified by
its tag.
--list-image-attribute[=NAME]
List restricting PostgreSQL expressions for presentation project NAME,
or for all presentation projects. If --tag is specified, list only
matching expressions.
Fallback: *
--tag=STR
Identifying tag for the restriction. Should be both short and
descriptive as it is shown as a selectable item on HTTP client.
--sql-clause=STR
Boolean PostgreSQL expression, to be used as an AND clause. Should
yield FALSE for images that are to be excluded.
Connect A Presentation Project To A Table Of Auxiliary Data:
Arbitrary data from tables not directly belonging to any Phoros
project can be connected to a presentation project by means of a view
named phoros-<presentation-project-name>-aux-point with columns
coordinates (geometry), aux-numeric (null or array of numeric), and
aux-text (null or array of text).
The array elements of both aux-numeric and aux-text of auxiliary
points can then be incorporated into neighbouring user points during
user point creation.
To match the array elements to the labels shown on HTTP client
(defined by --aux-numeric-label, --aux-text-label), NULL array
elements can be used act as placeholders where appropriate.
Also, a walk mode along auxiliary points becomes available to the HTTP
client. PL/pgSQL function
phoros-<presentation-project-name>-thread-aux-points is created to
this end.
In order to be accessible by Phoros, auxiliary data must be structured
rather simple (a single table which has a geometry column and some
numeric and/or text columns). You may want to create a simplifying
view if your data looks more complicated.
--create-aux-view=NAME
Connect table of auxiliary data with presentation project NAME by
creating a view.
--aux-table=NAME
Name of auxiliary table. It may reside either in Phoros' native
database or in an auxiliary database (which is common to all
projects). It must have a geometry column.
--coordinates-column=NAME
Name of the geometry column (which must contain geographic
coordinates, SRID=4326; and which should have an index) in the
auxiliary data table.
Default: the-geom
--numeric-column=NAME
Name of a numeric column in the auxiliary data table. An empty string
defines an empty placeholder column. Repeat if necessary.
--text-column=NAME
Name of a text column in the auxiliary data table. An empty string
defines an empty placeholder column. Repeat if necessary.
Manage User Points:
Backup/restore of user points; especially useful for getting them
through database upgrades.
--get-user-points=NAME
Save user points of presentation project NAME.
--store-user-points=NAME
Store user points previously saved (using --get-user-points or
download button in Web interface) into presentation project NAME.
--json-file=PATH
Path to GeoJSON file.
Manage Presentation Project Users:
--create-user=ID
Create or update user (specified by their alphanummeric ID) of certain
presentation projects, deleting any pre-existing permissions of that
user.
--user-password=PWD
User's password.
--user-full-name=STR
User's real name.
--user-role=TYPE
User's permission on their projects. One of "read", "write", or
"admin" where "write" is the same as "read" plus permission to add
user points and delete them if written by themselves (or by unknown
user); and "admin" is the same as "write" plus permission to delete
points written by other users.
Default: read
--presentation-project=NAME
Presentation project the user is allowed to see. Repeat if necessary.
--delete-user=ID
Delete user.
--list-user[=ID]
List the specified user with their presentation projects, or all users
if no user is given.
Fallback: *