.TH "zoph" "1" "12 Oct 2010" "Jeroen Roos" "User Commands"
.SH "NAME"
.LP 
zoph \- CLI interface to Zoph
.SH "SYNTAX"
zoph
[\fI\-\-instance\fP "instance"]
[\fI\-\-import\fP]
[\fI\-\-update\fP]
[\fI\-\-new\fP]
[\fI\-\-help\fP]
[\fI\-\-version\fP]
[\fI\-\-album\fP "album"]
[\fI\-\-category\fP "category [, category]"]
[\fI\-\-person\fP "first_name last_name [, first_name last_name]"]
[\fI\-\-photographer\fP "first_name last_name"]
[\fI\-\-location\fP ["place_title"]
[\fI\-\-fields\fP name="value"]
[\fI\-\-path\fP path]
[\fI\-\-[no]thumbs\fP]
[\fI\-\-[no]exif\fP]
[\fI\-\-[no]size\fP]
[\fI\-\-[no]dateddirs\fP]
[\fI\-\-[no]hierarchical\fP]
[\fI\-\-verbose\fP]
[\fI\-\-copy\fP]
[\fI\-\-move\fP]
\fI\-\-useids\fP id ... | \fIimage ...\fP

.SH "DESCRIPTION"
\fBzoph\fR is the command line importer for the Zoph (Zoph Organizes
PHotos) web photo management system.
.br
Any fields specified will be applied to every photo imported.  Any albums,
categories, people or places referred to must already be present in the
database.
.br 
Imported photos are moved or copied (depending on whether \fI\-\-copy\fR was specified) from their current location and
stored in in a directory below IMAGE_DIR - dependent on \fI\-\-path\fR, \fI\-\-dateddirs\fR and \fI\-\-hierarchical\fR settings. The MySQL database stores all the attributes and references to the images.
.br
Photos can appear in multiple albums and categories, and multiple people can be
in a photo. To handle this, you can either pass a comma separated list or set
the flag multiple times. 
If multiple people appear in a photo, specify them in left to right, front to
back order.
.SH "OPTIONS"
The `"' around arguments are needed to prevent breaking up around whitespace or
the shell interpreting special characters. If an album name consist of a single
word you can omit them.
.TP
\fB\-\-instance, -i\fR
.IP
You can have multiple Zoph installations on one system. For example a Zoph installation for yourself and one for a family member or friend, or if you are a Zoph developper, a production and a development  version. The webinterface can determine which installation your are using by the URL you are using. The command line interface does not have an URL thus it needs a different way to find out which instance of Zoph is used.

By default, the first instance in zoph.ini is used.
.TP
\fB\-\-import, -I\fR
.IP
The list of photos given will be imported in Zoph. This is the default.

.TP
\fB\-\-update, -u\fR
.IP
Zoph will try to find the given list of photos in the database and apply the options to those photos. You can either give a list of filenames or a list of id's, see \fI\-\-useIds\fR.
.TP
\fB\-\-new, -N\fR
.IP
Create albums, categories, places and people from CLI.
Use \fI\-\-album\fR "new album", \fI\-\-category\fR "new category", \fI\-\-person\fR "new person", \fI\-\-place\fR "new location". The new object will be created directly under the root unless \fI\-\-parent\fR is specified. See \fI\-\-person\fR for details on how Zoph determines what's the first and second name.
.TP 
\fB\-\-help\fR
.IP 
Lists all supported options and quits
.TP 
\fB\-\-version, -V\fR
.IP 
Show the current Zoph version.
.TP 
\fB\-\-album, --albums, -a\fR \fI"album, [, album]"\fR
.IP 
put the references to the image(s) into \fIalbum(s)\fR
.TP 
\fB\-\-category, --categories, -c\fR \fI"category [, category]"\fR
.IP 
put the references to the image(s) into \fIcategory(s)\fR
.TP 
\fB\-\-photographer, -P\fR \fI"first_name last_name"\fR
.IP 
store \fIfirst_name last_name\fR as the photographer of image(s)
.TP 
\fB\-\-person, --persons, -p, --people\fR \fI"first_name last_name [, first_name last_name]"\fR
.IP 
Specify one or multiple persons that appear on the photos specified. You can specify --person multiple times.
.PP
.IP
The name of a person or a list of persons separated by commas. The person must pre-exist in the database. When using \fI\-\-new\fR to add new persons to the database, Zoph will try to determine which parts of the name are first, middle and last. If a name is a single word ("John"), Zoph assumes this is the first name. If a name is two words ("John Doe"), Zoph will assume this is the first and last name. If a name is 3 or more words, Zoph will assume the first word is the first name, the second is a middle name and all remaining words are the last name. If this does not give the correct results, you can choose to separate by colon (":") instead of space. Zoph will then set the part before the first colon to first name, then middle, then last and finally 'called'.
.TP 
\fB\-\-location, -l, --place\fR \fI"place_title"\fR
.IP 
put the references to the image(s) into location
.TP 
\fB\-\-fields, -f, --field\fR \fIname="value"\fR
.IP 
set the image(s) field \fIname\fR to \fIvalue\fR; common fields are title
(text, 64 chars max), view (text, 64 chars max), description (text), rating
(1..10) or level (1..10); possible fields are from the MySQL database, table
photos; 
.br
\fBview\fR can be used to describe what can be seen in the photo.  Often this
is covered by the location field but sometimes you might want to be more
specific, or to describe something you don't want to store in the database as a
location (\fBview\fR is just a string).  In the demo the \fBview\fR field is
used in a photo of Big Ben in London: the location is set to Parliament (since
that was where the photographer was standing) and the \fBview\fR to Big Ben
(since that was what where the photographer was looking at).
.br
In the \fBdescription\fR field you can store additional information that
doesn't fit elsewhere.
.br
\fBlevel\fR is used for access privileges.  When someone is granted permission
to view an album, they are also granted an access \fBlevel\fR for that album.
They will be able to view photos in that album whose \fBlevel\fR is less than
or equal to their access \fBlevel\fR.  This is so you can selectively exclude
photos by giving them a higher \fBlevel\fR.
.TP 
\fB\-\-thumbs\fR,\fB -t\fR / \fB--nothumbs\fR,\fB --nothumbs\fR,\fB -n\fR
.IP 
Specify whether thumbnails should be created.

When importing (\fI\-\-import\fR), the default is to create thumbs. When updating (\fI\-\-update\fR), the default is to not create thumbs.

Use these commands to overrule the defaults. If you want to recreate thumbs for already imported photos, use \fI\-\-thumbs\fR. If you do not want to create thumbnails while importing, use \fI\-\-no-thumbs\fR.
.TP
\fB--exif, --EXIF\fR / \fB--no-exif, --noexif, --no-EXIF, --noEXIF\fR
.IP
Specify whether EXIF data should be read.

When importing (\fI\-\-import\fR), the default is to read EXIF data. When updating (\fI\-\-update\fR), the default is to not read EXIF data.
.TP
\fB--size\fR / \fB--no-size\fR, \fB--nosize\fR
.IP
Specify whether Zoph should update the dimensions of the photo stored in the database.

When importing (\fI\-\-import\fR), the default is to update database with dimensions of the image. When updating (\fI\-\-update\fR), the default is to not update the size information.

Use these commands to overrule the defaults. If you want to update the information stored in the database when updating, use \fI\-\-size\fR. If you do not want store size information while importing (although I see no real use for this), use \fI\-\-no-size\fR.
.TP
\fB--useids\fR, \fB--useIds\fR, \fB--use-ids\fR, \fB--useid\fR, \fB--use-id\fR
.IP
When updating photos it can be useful to be able to specify database ids instead of filenames.

You can specify a list of ids instead of a list of filenames. You can either specify a single id or a range of ids. Keep in mind that the list of filenames or ids are the \fIlast\fR options of the command and do not necessarily follow the \fI\-\-useids\fR option.

You can specify ids as single numbers or ranges. For example:

zoph --update --useids 2 5 11-20 56

Without specifying this option, \fBzoph\fR assumes filenames are used. Specifying this option implies \fI\-\-update\fR is used. 
.TP
\fB--move\fR / \fB--copy\fR
.IP
When importing photos, you can either import a copy of the photo or move the photo into the Zoph image directory. By default, files are moved. 

If the file imported is a symlink, in case of --move, a copy of the file the symlink points to is imported and the symlink is deleted. In case of --copy, the symlink is not deleted.

.TP 
\fB\-\-dateddirs\fR, \fB\-\-datedDirs\fR, \fB\-\-dated\fR, \fB\-d\fR / \fB--no-dateddirs\fR \fB\-\-no-datedDirs\fR, \fB\-\-nodateddirs\fR, \fB\-\-nodatedDirs\fR 
.IP 
put photos in YYYY.MM.DD directories, which are automatically created from the
date in the EXIF header, or, when no date is found in the EXIF header, the file date. The directories are created below \fIpath\fR
.TP 
\fB\-\-hierarchical\fR, \fB--hier\fR, \fB-H\fR / \fB--no-hierarchical\fR, \fB--no-hier\fR, \fB--nohierarchical\fR, \fB--nohier\fR 
.IP 
when given together with the \-\-datedDirs option, the dated directories are
created YYYY\/MM\/DD (instead of YYYY.MM.DD), thus creating a hierarchical
directory tree.
The directories are created below \fIpath\fR
.TP
\fB\-\-hash\fR / \fB\-\-no\-hash\fR
.IP
As of v0.8.4 Zoph stores a hash of each photo in the database. This is currently only used for the 'share photo' feature. In the future other features will use this, as it will allow Zoph to detect whether a photo has been changed.
The default is to generate a hash or update the hash when \fI\-\-update\fR is used.
.TP
\fB\-\-parent\fR
.IP
When adding new objects to the database using the \fI\-\-new\fR option, you can determine where in the tree an album, category or place will be placed by specifying \fI\-\-parent\fR.
.IP
If you do not specify a parent, the new object will be placed directly under the root.
.IP
\fI\-\-parent\fR must precede the actual album, category or place. The parent is only set for the next \fI\-\-album\fR, \fI\-\-category\fR or \fI\-\-place\fR.
.TP
\fB\-\-autoadd\fR, \fB\-A\fR, \fB\-\-auto-add\fR
.IP
You can use \fI\-\-new\fR to add albums, categories, places and people from CLI, with autoadd you can add them in the same run as you are importing photos. Zoph will add any album, category, etc. you have specified, but does not exist. However, to protect you from every typo to be automatically added to the database, only items preceded with \fI\-\-parent\fR will be added, unless you specify \fI\-\-addalways\fR. Of course this only works for albums, categories and locations, and not for persons and photographers.
.IP
.TP
\fB\-\-addallways\fR, \fB\-w\fR, \fB\-\-add-alwys\fR
.IP
When using \fI\-\-autoadd\fR, zoph protects you from every typo to be automatically added to the database by only adding albums, categories and location preceded with \fI\-\-parent\fR. To overrule this behaviour, use \fI\-\-addalways\fR, which causes them to be added under the root album, category or location.
.TP
\fB\-\-recursive\fR, \fB\-r\fR
.IP
Recursively go through directories added to the file list and import photos found in those dirs as well.
.TP
\fB\-\-dirpattern\fR
.IP
With \fI\-\-dirpattern\fR, you can automatically assign albums, categories, people, photographer, location or path based on the directories the photos are in. You do this by specifying a pattern, based on which Zoph will use directory names to assign to correct organizer. This pattern consists of a list of letters, where each letter is a directory: \fBa\fR (album), \fBc\fR (category), \fBl\fR (location), \fBp\fR (person), \fBP\fR (photographer) and \fBD\fR (path).
.IP
This option makes no sense if you do not specify \fI\-\-recursive\fR as well.
.TP
\fB\-\-verbose\fR
.IP
show verbosely whats going on (not implemented in v0.8.4)
.TP
\fB\-\-path\fR \fIpath\fR
.IP 
the path relative to IMAGE_DIR (set in config.inc.php), where the images are physically stored
.TP 
\fIfile ...\fR
.IP 
The filenames or database ids (in case \fI\-\-useids\fR is used) of the image(s) to be imported or updated.
.SH "EXAMPLES"
Import \fBIMG_1300.JPG\fR and place it in the album \fBSummer\fR and category \fBLandscapes\fR:
.IP 
zoph --album "Summer" --category "Landscapes" IMG_1300.JPG
.LP 
Import \fBjohn.jpg\fR and place it in the album \fBFamily\fR, category \fBPortraits\fR and specify \fBJohn Doe\fR is in this picture:
.IP 
zoph --album "Family" --category "Portraits" --person "John Doe" john.jpg
.LP
Create a new album called \fBsummer 2011\fR under the root album:
.IP
zoph --new --album "Summer 2011"
.LP
Create new albums called \fBSummer 2011\fR and \fBWinter 2011\fR under the \fBHolidays\fR album:
.IP
zoph --new --parent "Holidays" --album "Summer 2011, Winter 2011"
.LP
Create new albums called \fBSummer 2011\fR and \fBWinter 2011\fR under the \fBHolidays\fR album and an album \fBTrees\fR under the root album:
.IP
zoph --new --parent "Holidays" --album "Summer 2011, Winter 2011" --album "Trees"
.LP
Create new albums called \fBSummer 2011\fR and \fBWinter 2011\fR under the \fBHolidays\fR album and an album \fBTrees\fR under the \fBNature\fR album:
.IP
zoph --new --parent "Holidays" --album "Summer 2011, Winter 2011" --parent "Nature" --album "Trees"
.LP
Create a new album called \fBSummer 2011\fR under the \fBHolidays\fR album and a category \fBTrees\fR under the \fBNature\fR category:
.IP
zoph --new --parent "Holidays" --album "Summer 2011" --parent "Nature" --category "Trees"
.LP
Import all files in the current directory and the directories below. For each path, assign the name of the first directory as photographer, the second as album, and the third, fourth and fifth as categories.
.IP
zoph -r --dirpattern "Paccc" *
.LP
For more examples, see the wikibooks documentation.
.SH "RETURN VALUES"
.LP
0: success
.br
1: no arguments given (try --help)
.br
2: no files to import
.br
10: image not found
.br
20: person not found
.br
30: location not found
.br
40: album not found
.br
50: category not found
.br
90: \fIzoph.ini\fR not found
.br
91: instance not found
.br
95: CLI user not admin
.br
96: CLI user not valid
.br
97: CLI_USER not defined in zoph.ini
.br
99: API not compatible
.br
250: Cannot access arguments
.br
254: Unknown error
.SH "SEE ALSO"
.LP 
zoph.ini(5), a description of the zoph.ini configuration file
.br
http://en.wikibooks.org/wiki/Zoph, the Zoph documentation WikiBook
.SH "AUTHORS"
.LP 
zoph was written by Jason Geiger <zoph@nother.net> and is now maintained by Jeroen Roos (jeroen@zoph.org)
.LP 
this manpage was created for zophImport.pl by Mark Cooper, edited by Edelhard Becker <becker@edelhard.de> and Jeroen Roos <jeroen@zoph.org>. With the release of Zoph 0.8.2, it was rewritten by Jeroen Roos <jeroen@zoph.org> for the \fIzoph\fR CLI tool.