| HelpSet Table of Contents | Back to Project Home Page |
Next to the Project Hirtius application itself, a set of ancillary scripts has been provided that may serve a wide variety of purposes:
These scripts are all provided in the ./scripts/ folder of the distribution archive, accompanied by a README file that contains a summary of this document. All of these scripts are written in Perl (except for the Makefile, of course).
We'll describe each one in turn below:
What's more, most of these scripts use a (per-user) central configuration file to store default values for their parameters. Please refer to the Global scripts configuration file section below for information on how to install and use that file. The exact parameters used by each script, their meaning and the permissible values will be discussed in the section devoted to the scripts in question.
Purpose:
bulk_edit allows you to cycle through all your Slides (or a
selected subset of them) and edit the same field for all of them (one
field at a time). So it's not that the specified field will be set to the
same unique value for all selected Slides. You will be asked, for each
Slide in the selected set, to give a new value for the specified
field, and these values may all be different.
UTF-8 support: Perl is not multi-byte safe in itself, but the script doesn't perform any manipulation on the strings entered by the user. They are sent 'as-is' to the server, which means that multi-byte characters are preserved and provided your shell has been set for UTF-8 (the default under Linux these days), you should be OK.
Installation:
The script requires the following in order to work:
It is recommended to install this script someplace in the user's PATH, such as /usr/local/bin.
Usage:
Invoque online help for details:
$ bulk_edit -h
Here is its output:
./bulk_edit sequentially edits field 'field' for all slides. usage: ./bulk_edit [options] Options: -h/--help : help -> this message -f/--field F : edits field 'F' (required) -w/--where W : uses WHERE clause 'W' -u/--dbuser U : connects to the DB as user 'U' (default [hirtius]) -n/--dbname N : connects to the DB named 'N' (default [hirtius]) -H/--dbhost H : connects to the DB on server 'H' (default [localhost]) -d/--debug : debug -> turn debug mode on (def. off) WARNING: the DB connection will be opened as 'hirtius@localhost'.
Configuration:
This script uses the global configuration file ~/.hirtiusadmrc
(see the Configuration section below).
Configuration parameters used:
| Section | Parameter | Meaning and value |
|---|---|---|
| global | db_host(*) | Host name where the Hirtius DB is located |
| global | db_user(*) | User account used to connect to the Hirtius DB |
| global | db_name(*) | Name of the Hirtius DB |
*) Ensure that the value for this parameter matches the one defined in the Global Definitions File!
Purpose:
card_reminder is meant to be scheduled through cron, and run at
regular intervals against the 'hirtius' database. It will check the
validity of library cards and warn the user about any of his/her cards
that are about to expire (the number of days before expiration that
will trigger a warning can be customized).
Even though written in Perl, this script will use and parse the Project Hirtius Global Definitions File.
The proper working of this script rests on the following database fields:
Installation:
Please refer to the ./INSTALL file at the root of the distribution
archive.
The script requires the following in order to work:
Usage:
Invoque online help for details:
$ ./card_reminder -h
Here is its output:
usage: ./card_reminder [options] Options: -h/--help : help -> this message -b/--before D : warn 'D' days before exp. (def. 15) -c/--cfgfile F : configuration file (def. /srv/www/htdocs/hirtius/definitions.inc) -d/--debug : debug -> turn debug mode on (def. off)
Purpose:
chhtuser will be used internally by Project Hirtius user accounts
management pages in order to effect the renaming of user IDs in the
htpasswd file. The location of that file is passed as parameter to
the script.
Installation:
Please refer to the ./INSTALL file at the root of the distribution
archive.
The script requires the following in order to work:
Usage:
Invoque online help for details:
$ ./chhtuser -h
Here is its output:
Renames a user account in 'htpasswd'-format password files. usage: ./chhtuser [options] <file> <oldUID> <newUID> Options: -h/--help : help -> this message -d/--debug : debug -> turn debug mode on (def. off)
Purpose:
Quick hack to uppercase all subdirectories beneath the current one. Used it
to fix a mistake in the way Trays subdirectory structure had been
created. Beware: would process any subdirectory in the same way.
Installation:
Don't install it unless you actually need it. If you do, copy it to the
folder that contains all your Trays, and remove it afterward.
Purpose:
dd2dms converts between decimal degrees representation for
geographical coordinates and degrees, minutes and seconds notation. It
accepts the format used by Google Maps in its Search field.
Installation:
It is recommended to install this script someplace in the user's PATH,
such as /usr/local/bin.
The script requires the following in order to work:
Usage:
Invoque online help for details:
$ dd2dms -h
Here is its output:
Convert decimal degrees into degrees, minutes, seconds.
usage: /usr/local/bin/dd2dms [options]
Options:
-s/--Gstring 'S' : full coordinate string (e.g. Google Maps URL)
Expected format: 'dec.lat,dec.long'
-L/--lat F : latitude (float)
-l/--long F : longitude (float)
-h/--help : help -> this message
-d/--debug : debug -> turn debug mode on (def. off)
Note: specify either '-s' or ('-l' and/or '-L')
Purpose:
exifmv automates the renaming of digital picture files based on a set
of embedded EXIF tags expressing the creation timestamp of the picture.
The script uses both 'CreateDate' and 'DateTimeOriginal' tags (some
cameras set both, some only one of them, but not always the same). The
new filename will have either the date or the date and time prepended to
the original filename.
Use case: avoiding picture files being overwritten during download if the camera cycles too fast through its automated file name generation (e.g., on my Nikon D90 the filename generator will return to DSC_0001.JPG each time I format the SD card).
In addition, the script will also "normalize" the file, i.e. convert the filename to lowercase and remove the execute bits if set.
Installation:
It is recommended to install this script someplace in the user's PATH,
such as /usr/local/bin.
The script requires the following in order to work:
*) The Perl module "Image::ExifTool" seems to be installed by default on OpenSuSE and documentation for the module is available at:
<http://www.sno.phy.queensu.ca/~phil/exiftool/ExifTool.html>
Usage:
Invoque online help for details:
$ exifmv -h
Here is its output:
Renames digital pictures based on EXIF tags. usage: ./exifmv [options] file(s)... Options: -h/--help : help -> this message -t/--time : includes time in addition to date (def. off) -r/--reprocess : allow reprocessing of image files (def. off) -n/--no-normalise : don't normalise filenames (def. on) -d/--debug : debug -> turn debug mode on (def. off)
Purpose:
get_exif dumps on stdout all EXIF tags defined in the digital picture
files specified on the command line. Used as a learning and debugging
tool while writing 'exifmv'.
Installation:
It is recommended to install this script someplace in the user's PATH,
such as /usr/local/bin.
The script requires the following in order to work:
*) The Perl module "Image::ExifTool" seems to be installed by default on OpenSuSE and documentation for the module is available at:
<http://www.sno.phy.queensu.ca/~phil/exiftool/ExifTool.html>
Usage:
Invoque online help for details:
$ get_exif -h
Here is its output:
Dumps all EXIF tags embedded in digital pictures. usage: ./get_exif [options] file(s)... Options: -h/--help : help -> this message -d/--debug : debug -> turn debug mode on (def. off)
Purpose:
Automates the process of generating a PDF file (for instance) out of a
LaTeX report created by Project Hirtius.
Installation:
Typically copied in the local directory where the user downloads LaTeX
reports created by Project Hirtius for further processing. It is
recommended to also store in the ./reports folder on the server, so
all users of the application can easily download it from there at the same
time they download the source file for their report.
Usage:
To build a PDF document based on a LaTeX report file named
slide_index-20121030-100558.tex, type:
$ make slide_index-20121030-100558.pdf
Other supported targets are PS and DVI.
To make the same report into a booklet, type:
$ make slide_index-20121030-100558_booklet.pdf
Once done, you can remove all generated files (Beware: this also includes the PDF) by typing:
$ make clean
In most cases, you'll want to move the resulting PDF some place else for safekeeping before cleaning!
Purpose:
Creates beneath the current directory a Tray directory structure
suitable for storing Project Hirtius digital Slides (or digitized
analog ones). Please refer to the Pictures Management Workflow for more information on how this
step fits into the global picture management workflow.
Use case: I typically use this script on my workstation, because this is where the master copy of the image folders (aka Trays) are kept. Each time a folder has been modified, I then use ./publish (see below) to push the new version on the web server hosting them. But of course, you could use it directly on the web server if you prefer doing it that way.
Please note: The logic of this script hardcodes my own Tray naming convention. Should you decide on a different naming convention, you will have to either modify this script accordingly, or write your own from scratch.
Installation:
The script requires the following in order to work:
It is recommended to install this script someplace in the user's PATH, such as /usr/local/bin.
Usage:
Invoque online help for details:
$ mkcdtray -h
Here is its output:
usage: ./mkcdtray [options]
Options:
-h/--help : help -> this message
-t/--tray T : tray_name -> uses 'T' as tray name
(format: '[0-9]{3}[ABPX]', e.g. 034X).
-s/--holds S : holds -> holds max. S slides (default: 120).
(max. = 255 [ff]).
-l/--relink : relink -> recreate symlinks in tray root
-n/--nohex : decimal -> uses decimal slot numbering (def. hex)
-d/--debug : debug -> turn debug mode on (def. off)
Configuration:
This script uses the global configuration file ~/.hirtiusadmrc
(see the Configuration section below).
Configuration parameters used:
| Section | Parameter | Meaning and value |
|---|---|---|
| trays | holds(*) | Default number of slots in a Tray (expressed as a decimal value). Supported range is between 1 and 255. |
| trays | hexnum(*) | Use hexadecimal numbering for Tray slots by default. |
*) Ensure that the value for this parameter matches the one you typically use when creating new Tray records on the Slide Trays Edition Page!
Purpose:
Handles the renaming of a tray structure, even one that is already
"populated".
Use case: to be used only if a mistake was made in naming the on-disk Tray structure at the time mkcdtray was first called to create it (see above).
Please note: The logic of this script hardcodes my own Tray naming convention. Should you decide on a different naming convention, you will have to either modify this script accordingly, or write your own from scratch.
Installation:
The script requires the following in order to work:
It is recommended to install this script someplace in the user's PATH, such as /usr/local/bin.
Usage:
Invoque online help for details:
$ mvtray -h
Here is its output:
usage: ./mvtray [options]
Options:
-h/--help : help -> this message
-s/--source S : uses 'S' as source tray name
(format: '[0-9]{3}[ABPX]', e.g. 034X).
-t/--target T : uses 'T' as target tray name
(format: '[0-9]{3}[ABPX]', e.g. 034X).
-i/--index I : index file -> name of the gallery index (default: 00gallery.html).
-d/--debug : debug -> turn debug mode on (def. off)
Configuration:
This script uses the global configuration file ~/.hirtiusadmrc
(see the Configuration section below).
Configuration parameters used:
| Section | Parameter | Meaning and value |
|---|---|---|
| gallery | index(*) | Name of the photo gallery HTML index file, as generated by tray_gallery_gen (see below). |
*) Ensure that the value for this parameter matches the one defined in the Global Definitions File!
Purpose:
Small ad-hoc script to ease the publishing of a tray structure from
a local workspace to a central web server (via an NFS-mounted share).
To fully automate your workflow, the present script may also call 'tray_gallery_gen' (see below).
Please note: The logic of this script hardcodes my own Tray naming convention. Should you decide on a different naming convention, you will have to either modify this script accordingly, or write your own from scratch.
Installation:
The script requires the following in order to work:
It is recommended to install this script someplace in the user's PATH, such as /usr/local/bin.
Usage:
Invoque online help for details:
$ publish -h
Here is its output:
usage: ./publish [options]
Options:
-h/--help : help -> this message
-t/--tray T : tray_name -> uses 'T' as tray name
(format: '[0-9]{3}[ABPX]', e.g. 034X).
-s/--store S : web store -> path to web store (default: /data/forum/dias).
-n/--no-gallery : do NOT generate gallery (def. ON)
-d/--debug : debug -> turn debug mode on (def. OFF)
Configuration:
This script uses the global configuration file ~/.hirtiusadmrc
(see the Configuration section below).
Configuration parameters used:
| Section | Parameter | Meaning and value |
|---|---|---|
| global | webstore(*) | Path to Hirtius webstore |
| trays | tray_gallery_gen | Path to 'tray_gallery_gen' script (should be '/usr/local/bin/tray_gallery_gen' if you followed these instructions) |
| trays | galgen | Whether or not the 'publish' script should call 'tray_gallery_gen' by default ('1' = yes, '0' = no) |
*) Ensure that the value for this parameter matches the one defined in the Global Definitions File!
Purpose:
This script is meant to be used in support of the project reporting feature
(see Projects Report Page), when Slide objects have been linked to the project
being turned into a LaTeX report. In a situation like this,
slide_extract would come in handy when preparing a lecture based on
that report, for instance.
slide_extract will retrieve from the Trays where they are kept, as local files, all slides linked to the specified project (or all those whose references are provided in the input file -- so you can retrieve a Slide set even if they're not part of a project). Once retrieved, these pictures can then easily be burnt to DVD, included in a slide deck or something to that effect, to serve as illustration during the lecture, for instance).
The script provides three different ways to specify the list of Slides to extract, using the following parameters:
A valid input file for the script could look something like this (in any case, any line that isn't recognised as a potential Slide reference is automatically ignored):
# This is a comment (will be ignored) D1234 D5678 D32 # Slide references are not case-sensitive: d98294
Installation:
The script requires the following in order to work:
It is recommended to install this script someplace in the user's PATH, such as /usr/local/bin.
The script can work from any host that has been granted remote access to both the 'hirtius' database(*) and the Slides webstore. If the webstore address is specified as a regular path, plain cp commands will be used to copy the Slides to the destination folder. If the webstore is specified as an URL, the wget utility will be used to download them.
(*) To grant your users remote access to the database for the purpose of this script, it is best to create a read-only MySQL-level user account for them. You can do so with the following SQL command: GRANT SELECT ON hirtius.* TO 'user'@'%' IDENTIFIED BY 'password'; (where 'user' is the user name, '%' means "from any host", and 'password' is the password the user will need to use when authenticating to MySQL, e.g. when prompted by the script).
Usage:
Invoque online help for details:
$ slide_extract -h
Here is its output:
Copies selected digital slides from trays to a designated directory. usage: /usr/local/bin/slide_extract [options] Options: -h/--help : help -> this message -p/--projid P : query slides linked to project 'P' (reqd -p XOR -i XOR -t). -i/--infile I : use input file 'I' for slides list (reqd -p XOR -i XOR -t). -T/--INXtag T : use INXtree tag 'T' for slides list (reqd -p XOR -i XOR -t). -o/--outdir O : target dir. for output (reqd). -r/--repobase R : slide repos. base path/URL (default [/srv/www/htdocs/dias]) -u/--dbuser U : connects to the DB as user 'U' (default [hirtius]) -n/--dbname N : connects to the DB named 'N' (default [hirtius]) -H/--dbhost H : connects to the DB on server 'H' (default [localhost]) -t/--tidlen T : uses T as TrayID length (default [4]) -l/--tll L : uses L as tag-level length (default [4]) -d/--debug : debug -> turn debug mode on (def. off) WARNING: the DB connection will be opened as 'hirtius@localhost' (unless specified otherwise).
Configuration:
This script uses the global configuration file ~/.hirtiusadmrc
(see the Configuration section below).
Configuration parameters used:
| Section | Parameter | Meaning and value |
|---|---|---|
| global | db_host(*) | Host name where the Hirtius DB is located |
| global | db_user(*) | User account used to connect to the Hirtius DB |
| global | db_name(*) | Name of the Hirtius DB |
| global | webstore(*) | Path to Hirtius webstore |
| trays | tidlen(*) | Length (in char.) of a Tray identificator |
| INXtree | tll(*) | Length (in char.) of a INXtree per-level identificator (see Concepts) |
*) Ensure that the value for this parameter matches the one defined in the Global Definitions File!
Purpose:
This script generates a basic, static "photo gallery" HTML index page for an
existing (and at least partly populated) Hirtius slide tray, allowing
for easy visualisation of its contents. The on-disk structure needs to have
been created by the 'mkcdtray' script (see
above), and it is recommended that the relevant
Tray record already exists in the Hirtius database as well.
The script will create thumbnails of all Slides contained in the Tray, will extract some EXIF properties from the original image file (such as their creation date) and will also query the Hirtius database for the Tray description.
For a fully automated workflow, 'tray_gallery_gen' can be called automatically by the 'publish' script (see above) each time you push a tray on-disk structure from your workspace to the server.
Installation:
The script requires the following in order to work:
It is recommended to install this script someplace in the user's PATH, such as /usr/local/bin.
Usage:
Invoque online help for details:
$ tray_gallery_gen -h
Here is its output:
Creates a static photo gallery for a published web store. usage: ./tray_gallery_gen [options] -tOptions: -h/--help : help -> this message -t/--tray T : tray name -> uses 'T' as tray ID (format: '[0-9]{3}[ABPX]', e.g. 034X). -u/--dbuser U : connects to the DB as user 'U' (default [hirtius]) -n/--dbname N : connects to the DB named 'N' (default [hirtius]) -H/--dbhost H : connects to the DB on server 'H' (default [eniac.heron.net]) -s/--store S : web store -> path to web store (default: /data/forum/dias). -U/--url U : base URL -> Hirtius app. URL (default: [http://hirtius.heron.net/]). -i/--index I : index file -> name of the gallery index (default: 00gallery.html). -c/--cpr C : colums per row (default: 5). -v/--vpix V : thumbnails height in pixel (default: 90). (bounds: 20 <= V <= 500). -Z/--skipDB : do NOT query Hirtius DB (def. off) -d/--debug : debug -> turn debug mode on (def. off)
Configuration:
This script uses the global configuration file ~/.hirtiusadmrc
(see the Configuration section below).
Configuration parameters used:
| Section | Parameter | Meaning and value |
|---|---|---|
| global | db_host(*) | Host name where the Hirtius DB is located |
| global | db_user(*) | User account used to connect to the Hirtius DB |
| global | db_name(*) | Name of the Hirtius DB |
| global | db_charset(*) | Character set used to encode textual information stored inside the Hirtius DB (defaults to 'utf-8') |
| global | base_url(*) | Base URL to Hirtius web-app. |
| global | webstore(*) | Path to Hirtius webstore |
| gallery | index(*) | Name of the photo gallery HTML index file to be generated by this script |
| gallery | thumbsdir(*) | Name of the Tray subfolder used to store Slides thumbnails (folder and contents created by this script) |
| gallery | cpr | Number of columns per row to be used when laying out the HTML gallery index page |
| gallery | vpix | Target thumbnail height in pixel (admissible range is between 20 and 500) |
| gallery | twxhratio | Target thumnails width by height ratio (max. thumbnails width is computed as height x ratio) |
| gallery | convert | Path to the 'convert' utility, part of ImageMagick software package |
| gallery | debuglevel | Debug level (set higher than '1' for extra debugging messages) |
*) Ensure that the value for this parameter matches the one defined in the Global Definitions File!
Purpose:
This script is used to read the EXIF data fields from a set of digitial
pictures identified as "slides" in Hirtius and upload them to the
database, linked to the appropriate Slide record.
The matching between the physical digital picture file and the Slide record is based solely on the digital picture file name (so it has to follow Hirtius' conventions -- please refer to the Pictures Management Workflow for instructions).
The script is capable of processing a single file, a set of individual files, or entire directory trees (typically those created by Project Hirtius to store "digital slides trays" -- see the 'mkcdtray' script above). If that on-disk Tray structure already contains gallery data (thumbnails, index file) as generated by 'tray_gallery_gen', these extraneous files will be silently ignored.
Installation:
The script requires the following in order to work:
It is recommended to install this script someplace in the user's PATH, such as /usr/local/bin.
The script can work from any host that has been granted remote access to the 'hirtius' database, but it needs direct filesystem access to the digital picture files (access through a network share is OK, HTTP access to the webstore is not supported yet). This script needs write access to the database, so it should most likely be run by the local admin as the database owner.
Usage:
Invoque online help for details:
$ upload_exif -h
Here is its output:
./upload_exif uploads the EXIF data for individual slides or entire trays to the Hirtius DB. usage: ./upload_exif [options] <file(s)|dir(s)> Options: -h/--help : help -> this message -u/--dbuser U : connects to the DB as user 'U' (default [hirtius]) -n/--dbname N : connects to the DB named 'N' (default [hirtius]) -H/--dbhost H : connects to the DB on server 'H' (default [localhost]) -d/--debug : debug -> turn debug mode on (def. off) -s/--simulate : simulate -> turn fake mode on (def. off) -S/--slow : slow -> insert 1 row at a time (def. fast) -w/--wipe : wipe -> first wipe data if present (def. off) WARNING: the DB connection will be opened as 'hirtius@localhost' (unless specified otherwise).
Configuration:
This script uses the global configuration file ~/.hirtiusadmrc
(see the Configuration section below).
Configuration parameters used:
| Section | Parameter | Meaning and value |
|---|---|---|
| global | db_host(*) | Host name where the Hirtius DB is located |
| global | db_user(*) | User account used to connect to the Hirtius DB |
| global | db_name(*) | Name of the Hirtius DB |
| exif | exif_up_mode | Default mode for EXIF upload to Hirtius DB (supported values are 'fast' or 'slow') |
*) Ensure that the value for this parameter matches the one defined in the Global Definitions File!
The global configuration file used by most of the scripts described above is to be installed in the home directory of each and every user liable to use the scripts in question, by copying the template provided in the ./scripts/ folder of the distribution archive and called hirtiusadmrc.tmpl.
Once copied inside the user's home directory, that file should be renamed '~/.hirtiusadmrc' and can then be customized to the user's liking. Some parameters in the template file have no default value and should always be customized:
| Section | Parameter | Meaning and value |
|---|---|---|
| global | base_url | Base URL to Hirtius web-app. It could specify a host FQDN alone, or the FQDN followed by a path depending on whether or not a VHost has been defined inside the Apache server. |
| global | webstore | Path leading to the Hirtius webstore, i.e. the top
directory that contains all Tray folders. That path can be either
local or remote (e.g. NFS share), but it should be writeable by the
user that calls the script (except in the case of 'slide_extract'
where R-O access is enough) and be published by your Apache server for
remote HTTP access. Several scripts make use of this parameter, but among those only 'slide_extract' would accept a URL for its value. This explains why a regular directory path is expected to be provided in '~/.hirtiusadmrc', and why the other scripts will report an error if a URL is specified instead. To use an URL with 'slide_extract', specify it on the command-line with the '-r' parameter (see above). |
Important notes:
See also:
Project Hirtius, © Les Ateliers du Héron, 2012.
Last updated: Tuesday, Aug. 24, 2021.
| HelpSet Table of Contents | Back to Project Home Page |