Ozi Photo Tool

Release 2.8 - January 2007

Index

Licence
Help

   
Introduction
   
Forums
   
Registration
   
Program Requirements
   
Getting Started - Importing data into OziPhotoTool
   
Getting Started - Calibrating Times
   
Getting Started - Generating Output
       
Waypoint Generation
        Map Feature Generation
       
OziExplorer Interface
       
Copied
Images
        External Execution
    Other Features
       
Linking Other File Types
       
Photo Waypoint Browser

       
HTML Generation
        GoogleEarth KML/KMZ Generation
       
Internal Preview
       
Configuration Files
    Advanced Features

       
String
Replacement Codes
       
Custom String
Replacement Codes
       
Text Output
       
General Properties
       
Time Delta

       
Command Line Support

   
Other Questions

    Acknowledgements


License

OziPhotoTool is a shareware application. Its installation and use is subject to the following terms and conditions. You are granted a License to use OziPhotoTool if you agree to them. If you do not agree with them you may not use OziPhotoTool and you must remove it from your system:



Help

Introduction

OziPhotoTool combines the technology of a GPS receiver and a digital camera to automatically keep a record of where digital photos were taken. It is designed to be used in conjunction with OziExplorer (www.oziexplorer.com) however the only requirement is that input track files are in OziExplorer format. Most digital cameras have “EXIF” metadata stored as part of the photo. This includes is the date and time the photo was taken. Many GPS units have “tracklogs”. The GPS keeps a record of points that the unit has traveled over, including the time at each point. OziExplorer can read “tracks” from many different GPS units.

OziPhotoTool takes the digital photos and a track from OziExplorer and determines where the GPS unit was at when the photo was taken. As long as the GPS was in the same location as the camera this represents the location of the photo. OziPhotoTool outputs the linkage between the photo and its location by creating an OziExplorer waypoint file, generating map features on OziExplorer maps, and/or watermarking the photos.

This program was tested with a Canon Powershot G2 digital camera and a Garmin e-Trex GPS.

Forums

Visit the OziPhotoTool help and discussion forums at http://www.oziphototool.com

Registration

From version 2.0 registration is required for commercial or government users, and is strongly encouraged for all others. All features of OziPhotoTool are available in the unregistered version except that waypoint file generation is limited to processing only the first five images in the image file list.

To register visit http://www.oziphototool.com for details.

OziExplorer Requirements

Many features of OziPhotoTool require the latest registered version of OziExplorer to function properly. It is possible to use the un-registered version of OziExplorer to save a track file then import this into OziPhotoTool. OziPhotoTool communicates with a running version of OziExplorer to do things like saving the current track file automatically, saving a map image for html generation, determining the x,y pixel coordinates of photowaypoints, etc. OziExplorer requires that it be registered in order for many of these features to work.

Getting Started - Importing data into OziPhotoTool

The first part of the process is to ensure everything is installed correctly and create some data to work with. If you just want to test the tool use the data supplied in the "testdata" directory. You should have a blank map and the test track file opened in OziExplorer. In more detail:

1.    Ensure you have an up to date version of OziExplorer, version 3.95.3e or later is recommended.

2.    Make sure you have a Java 1.4 compatible JVM installed or use the installer that includes a JVM. OziPhotoTool will check the java version you are using and exit if it is not appropriate.

3.    Clear the current track from you GPS and go for a walk. Take a few photos along the way.

4.    Ensure you take at least one photo of your GPS unit that shows the date and time setting. This photo will be used to calibrate the GPS and the Camera. If you are sure your GPS and camera are set to the same time, and UTC offsets of the computer and camera are the same, you may skip this step.

5.    Run OziExplorer and download the track from the GPS. Then save the track to a file somewhere. Leave OziExplorer running.

6.    Download the photos and make sure they are saved as *.jpg files somewhere. Note that you should be careful to ensure that if you edit the files the EXIF data is copied across. Use an image viewer like PhotoStudio (http://www.stuffware.co.uk) to check if your images have metadata.

7.    Run Ozi Photo Tool (use run.bat if you do not have a properly installed version and you have your own JVM).

8.    Add the image files to the image file list (in the middle). You can add images by selecting the image files through a file chooser (you can select directories as well – all .jpg or .jpeg files in those directories will be included), pasting files copied from windows, or dragging files from windows.  

9.     Add track files to the track file list (on the left). The easiest way to do this is click the button to get the active track from OziExplorer. You can also add the track file through the file chooser (multiple tracks and directories can be selected), pasting files copied from windows, or dragging files from windows.  

The buttons used to add and view image and track files are described below.

Add image or track files to the respective list if they are not there already. You can add multiple files. Selecting directories will add all image or track files from that directory (not recursively)
Remove the selected image or track files from the respective list. This does not affect the files. The delete key will also remove files from the respective list.
Remove all image or track files from the respective list.
Preview the selected image. Note you can also double click on an image in the list to get a preview.
Add the "Active" track from OziExplorer to the track file list. The "Active" track (or track number 1) will be saved to a file in the OziPhotoTool temp directory and added to the track file list.

Getting Started - Calibrating times

Perhaps the most confusing aspect of using OziPhotoTool is ensuring that your GPS and Camera times are calibrated. This is further confused by differing time zones of the Computer. OziPhotoTool can handle situations where you took the photos with your GPS time set in one zone, your camera in another, and then your computer in another. A more detailed discussion on times is given below. A few simple steps that work for most people are as follows.

1.    Open the Time Delta Manager in the Tools menu.

2.    If you are sure that your Camera, GPS and Computer are all set to the same time, and in the same time zone, you can just click "Clear" then "Apply" and the time delta will be set to zero.

3.    If not sure, open the photo of your GPS that you will use for time calibration using the file chooser.

4.    Zoom and pan on the file until the time is visible in the top window.

5.    The computer time, including the total offset is shown on the first line. The total offset is the time zone offset plus any daylight savings time offset that may be applied.

6.    The next line shows the time read from the EXIF metadata information in the image above. Note that the EXIF information contains no information on GMT offset. You must enter this field as appropriate (by default it is the same as the computer offset).

7.     The next line is the time shown on the picture of the GPS. Here you should enter the time exactly as shown in the picture (converting to the 24 hour clock if appropriate). You should also enter the offset. Note that in many GPS that the time offset is only applicable to the time displayed in the GPS unit, the time stored with tracks is usually with a GMT offset of zero. In this case you should enter the GPS offset of the time displayed.

8.    Click on Apply and the Camera GPS time difference in seconds will be calculated and stored. For a more detailed discussion on how this is done and how it is used in generating waypoints see below.

Getting Started - Generating output

After adding image and track files, and ensuring that your times are calibrated,  you can generate output. Clicking on generate should bring up the generate setting dialog by default. If it does not you can bring up generate settings at any time from the File menu. OziPhotoTool can generate OziExplorer waypoint files, add map features to OziExplorer map files, and/or create watermarked images with location information.

WARNING - It is strongly recommended that you back up all important images, track files, map files and waypoint files before commencing generation. OziPhotoTool is designed not to affect this information in most cases however until you are sure it is doing what you want be careful.

Waypoint Generation

If waypoint generation is enabled the waypoint file specified will be generated. OziPhotoTool will automatically overwrite any existing waypoint file with that path and name. When you first run OziPhotoTool the output file is set to "out.wpt" in the output directory.  If Append to existing is selected then new waypoints will be created to reflected the photo locations and added to the existing waypoints, in this case the header information will not be affected. If Load to OziExplorer is selected the generated waypoint file will be loaded to OziExplorer if it is running.

The waypoint file properties can be altered by clicking on the properties icon. Note the text codes below. The four header lines are output first. The remaining fields are created for each waypoint on the one line (representing each photo). They are comma delimitated. More information on the waypoint file format is included here.

In OziExplorer you can right click on the waypoints and click open file attachment to open the relevant image in the default image viewer. You may like to change the FileAttachementName field in the waypoint file properties from &file to &wmfile to link to the watermarked files instead - this is the default with some configuration files (see the text replacement codes below).

Map Feature Generation

Map Features form part of OziExplorer map files. When map feature generation is enabled OziPhotoTool takes an input map file, adds map features to it that represent photo locations, and creates a new output map file that incorporates these map features. WARNING - if the input and output map file is the same the input file will be overwritten, this may be exactly what you want but be careful. If Append to existing is selected then map features will be added to those that already exist in the map file, if not then existing map features will be discarded. The map file specified as output will be loaded to OziExplorer if specified and OziExplorer is running. Note that even if map feature generation is turned off that this can be used to load a map file to OziExplorer.

The map features properties can be altered by clicking on the properties icon. Note the text codes below. OziExplorer help contains more information on the map file format that explains the map feature properties.

Map features do not contain as much information as waypoint files however they do have a preview of the File Attachment in the properties area (in OziExplorer).

OziExplorer Interface

OziPhotoTool needs OziExplorer to be running in order to load waypoint and map files to it. It is also required to do datum conversion for map file generation (if the track file and the map file are in different datum's), and is required for some HTML generation settings in the Photo Waypoint Browser. . You should specify the path to the OziExplorer executable. Note that if you are using a development version this should be the executable for that version.

You can also specify that all tracks in the track list be loaded to OziExplorer. In this case all tracks currently open in OziExplorer will be cleared and tracks in the track list loaded into OziExplorer. Note that this is limited to only the first 75 tracks.

Copied Images

When processing and image OziPhotoTool can make a copy of it. The copied image feature is primarily used for watermarking images however can also be used to embed a thumbnail in the copied image for faster loading in browsers, resizing an image, or embedding GPS information.

OziPhotoTool can create images with basic watermarks with a wide variety of information. The watermark is a round cornered rectangle with a line of text in it. The text is specified using the text codes below. When watermarking is enabled an image is created for each successful photo processed in the specified output directory. The image name is specified below the image output directory. By default this is opt&fnme. For example after using the text replacement codes detailed below an image named text.jpg will created a watermarked image called opttext.jpg. Note to link generated waypoints to the watermarked file instead of the original one change the fileAttachmentName field in waypointProperties from &file to &wmfile.

Even if a user does not want a watermarked image it may be advantageous to create one and specify drawText and drawBackground as false. By doing this you embed a small thumbnail in the image for faster loading by the photowaypoint browser. You may also want to do this if you wish to embed GPS Exif tags or resize copied images. The resize size is specified in the general property resizeImageSize.

The watermarked image properties are rather complex. These are detailed below.

Property Description Default Value
locy The distance from the (top or bottom) of the photo to the top left corner of the rectangle in pixels. Ignored if the vertical alignment is center 20
locx The distance from the (left or right) of the photo to the top left corner of the rectangle in pixels. Ignored if the horizontal alignment is center 20
verticalAlign The vertical alignment of the rectangle with regard to the photo. 0 - top, 1 -bottom, 2 - center Top
horizontalAlign The vertical alignment of the rectangle with regard to the photo, 0 - left, 1- right, 2 -center Left
drawBackground If true then the background rectangle is drawn false
backsizex The width of the rectangle in pixels  200
backsizey The height of the rectangle in pixels  20
backColor The color of the rectangle in Integer RGB format (consisting of the red component in bits 16-23, the green component in bits 8-15, and the blue component in bits 0-7) -414960
backAlpha The transparency of the background. 0.0 - fully transparent, 1.0 - solid color. 0.7
arc The radius of the rounding on the corners of the rectangle (in pixels) 5
text The text placed in the rectangle. See the text replacement codes below Lat:&dlat Long:&dlong
drawText If true the text is placed in the rectangle false
textx The horizontal alignment of the text in the rectangle 0 - left, 1- right, 2 -center center
texty The vertical alignment of the text in the rectangle 0 - top 1-bottom, 2 -center center
textFontName The font used for the text (Serif, SansSerif, Dialog, Monospaced, DialogInput, or one of the windows true type fonts) serif
textFontStyle 0-plain, 1-bold, 2-italic, 3-bold/italic plain
textFontSize font size in pixels 18
textColor The color of the text in Integer RGB format (consisting of the red component in bits 16-23, the green component in bits 8-15, and the blue component in bits 0-7) -65281
textAlpha The transparency of the text. 0.0 - fully transparent, 1.0 - solid color. 1.0
jpgCompression Compression of jpeg output images. 0.0 = fully compressed, 1.0 = no compression 0.85

External Execution

After processing an image to determine its location you can run an external program (or batch of external programs) after each image is successfully processed. This feature is primarily to further process the image with a third party application. Commands to be executed should be located in a text file. The location of this file can be specified in the Generation Settings panel. Any line beginning with # is ignored. All other lines are passed to the Runtime environment to execute in the order in which they are encountered after the text replacement codes detailed below are applied. All references to files should be relative to the OziPhotoTool installation directory or absolute.

OziPhotoTool is shipped with an unregistered version of exifedit.exe in the utils directory with permission from the author. This is one component of EXIFutils (www.hugsan.com/EXIFutils). The file exifeditbatch.txt contains contains appropriate commands to embed GPS EXIF tags into watermarked files. To embed EXIF tags into the original files replace &wmfile with &file in this exifeditbatch.txt. To ensure your originals are backed up remove the /b tag from the first line. For more information on EXIFutils visit www.hugsan.com/EXIFutils.

Other Features

Linking Other File Types

In addition to processing image files based on the date in EXIF information OziPhotoTool will also process any other file type based on the time the file was last modified. This may be used to link files such as short movie or audio clips that were recorded when images were taken. Files are added and removed from the other file list in the same way as the image file list.

Note that Other Files will create Waypoints and Map Features but are not subject to external batch processing. HTML generation is not currently supported for other file types and errors may be encountered.

Photo Waypoint Browser

The photo waypoint browser will take a waypoint file generated by OziPhotoTool and display the photo waypoints in date order. By default it uses the last waypoint file generated however you can select others. You can filter photo waypoints by date and by distance from a particular location. Photo waypoints are displayed in thumbnail format with brief information on the location, time and distance from the point selected. You can customize this information using the browserString property detailed below. Click on the thumbnail to open the photo in the internal preview panel or the default image viewer (depending on the internal_preview setting in the general settings). To change the number of images displayed you can change the browseNumImg property in general properties.

Note that distance calculations are approximate using the Great Circle distance calculation method found at http://www.ga.gov.au/nmd/geodesy/datums/calcs.jsp

Note also that photo waypoint times are in GMT+00:00.

HTML Generation

In the photo waypoint browser you can generate HTML output. HTML is generated from those photo waypoints that are displayed in the photo waypoint browser using the same filter conditions. You must specify an output file and a template to use for generation (some other properties are settable in the general properties area).

Advanced users may like to edit or produce their own html templates. In the htmltemplates directory there should be a directory for each template. You can add a new template directory and it will automatically appear in OziPhotoTool. In this directory there must be a number of input html files that are used as the basis for html generation. The input html files rely heavily on text replacement codes. It is recommended to use @@ rather than & in front of text replacement codes in html input files. You can specify what character string to use in the General Property htmlStringRepChar.

index.html (indexX.html)

This file will be copied to the output directory. Each instance of @@thumbs is replaced with a concatenation of the thumb.html document for each waypoint that meets the filter conditions. Each instance of @@thumbx is replaced with a concatenation of thumbx.html for each waypoint that meets the filter conditions where x is any integer from 0 to 100. See the index.html document in the included html templates for an ides of how to use these features. Files named indexX.html, where X is any integer from 0 to 100 will be treated in the same way as index.html.

thumb.html (thumbx.html)

For each photowaypoint this code will be copied to the relevant index.html file in the output directory to replace @@thumbs. Text replacement codes are used on each line of thumb.html before copying.

full.html

For each photowaypoint a file named &fnmx.html (with &fnmx replaced by the image file name) will be created in a directory called images in the output directory based on full.html. Text replacement codes are applied to each line.

Images

In addition to the index files, and those based on full.html, full sized images are copied to the images directory (refer to using images/@@fnmx.html). Thumbnails of each image are also placed in this directory (refer to images/@@fnmx_small.jpg). The thumbnail size can be specified in general properties.

OziExplorer Map

If the general property save_html_map is set to true then OziPhotoTool will attempt to save the current map image loaded in OziExplorer to the html output directory using the name given in the general property html_map_nane. This image will include any waypoints or tracks that are loaded in OziExplorer. If you want to have the waypoints displayed then you need to ensure that they are loaded in OziExplorer. The map can be referred to in html using @@map. The x,y locations of waypoints on the map image can be accessed using @@pointX and @@pointY. Note that these features rely on a registered version 3.95.3e or later of OziExplorer.

The map is cropped by default 100 pixels away from all included waypoints. This can be customized (or not cropped at all) in the General Properties dialog by altering crop_html_map. You can also resize the OziExplorer map that is saved as part of HTML generation. This will only work if "crop_html_map" is checked in the GeneralProperties. The scale of the resized OziExplorer map is controled by "mapZoomFactor" in GeneralProperties. If you do not plan to use the zoom leave it set at 1.0 and the cropped map size will not be changed. If you want to zoom an uncropped map then set "crop_html_map_X" and "crop_html_map_Y" values larger than the number of pixels from the edge of the map to the furtherest waypoint.

Copied Files

Any files in a directory titled tobecopied in the base directory of a HTML template directory are copied to the HTML output directory. This feature may be used for stylesheets for example.

Google Earth KML/KMZ Generation

In the photo waypoint browser you can also generate kml and kmz files for display in Google Earth. The concept is very similar to HTML generation. Like HTML generation a kmz file is generated from those photo waypoints that are displayed in the photo waypoint browser using the same filter conditions. You must specify an output file and a template to use for generation (some other properties are settable in the general properties area). When generating kmz files you can also include information about the track in the file. This allows the track to be displayed in Google Earth. The track files are read from the track file list.

Advanced users may like to edit or produce their own kml templates. In the kmltemplates directory there should be a seperate directory for each template. You can add a new template directory and it will automatically appear in OziPhotoTool if you close it down and restart. In this directory there must be a number of input kml files that are used as the basis for kml generation. The input kml files rely heavily on text replacement codes. It is recommended to use @@ rather than & in front of text replacement codes in html and kml input files. You can specify what character string to use in the General Property htmlStringRepChar.

The copied and altered kml files and images are temporarily copied to the oziphototool/temp/kmz directory. Prior to kml generation this directory is deleted to remove old files. After all kml and image files are complete the directory is zipped up and copied to the kmz archive specified. If you have Google Earth installed then you will be presented with an option to open the file.

Kml/kmz generation is not designed to produce the final version for sharing with others. Rather you should open the kmz file in Google Earth and add extra annotations to each image. If you spend a bit of time you will end up with some really cool looking output.

doc.kml

This file will be copied to the output directory. Each instance of @@thumbs is replaced with a concatenation of the thumb.kml document for each waypoint that meets the filter conditions. Each instance of @@thumbx is replaced with a concatenation of thumbx.kml for each waypoint that meets the filter conditions where x is any integer from 0 to 100. Each instance of @@tkpnts is replaced with a concatenation of the tkpnt.kml document for each trackpoint in every track in the track file list. Each instance of @@tkpntx is replaced with a concatenation of tkpntx.kml for each trackpoint in the track file list where x is any integer from 0 to 100. See the index.html document in the included html templates for an ides of how to use these features.

thumb.kml (thumbx.kml)

For each photowaypoint this code will be copied to the doc.kml file in the output directory to replace @@thumbs (or @@thumbx as appropriate) . Text replacement codes are used on each line of thumb.kml before copying.

tkpnt.kml (tkpntx.kml)

For each photowaypoint this code will be copied to the relevant doc.kml file in the output directory to replace @@tkpnt (or @@tkpntx as appropriate) . Text replacement codes are used on each line of tkpnt.kml before copying.

Images

In addition to the doc.kml in the root of the kmz file full sized images may be optionally copied to the images directory (refer to using images/@@fnmx.html). This is specified by checking kmzFullImageCopy in the General Properties area but it is disabled by default. Thumbnails on the other hand are enabled by default of each image are also placed in this directory (refer to images/@@fnmx_small.jpg). The thumbnail size can be specified in general properties.

Copied Files

Just like with HTML generation any files in a directory titled tobecopied in the base directory of a kml template directory are copied to the kml output directory.

Internal Preview

The internal preview panel is a basic panel that will display images. You can zoom in and out to some extent and pane a scroll pane to view different sections of the image. The raw EXIF date of the image is shown at the top of the preview pane. Note that the GMT offset displayed is that set in the time delta screen for the Camera GMT offset.

The top text panel contains the image's EXIF data. The format for this data is DIRECTORY.Tag   (Value). The DIRECTORY.Tag values can be used to extract the metadata and use them in string replacement codes using &metadataDIRECTORY.Tag&. Use CTRL-C to copy text from this panel and CTRL-V to paste into a properties dialog.

Configuration Files

From the File menu users can load and save OziPhotoTool configurations. By default these are stored in the inihelp/config directory. When saving a configuration all properties files, and the image, other, and track file lists are stored in a *.opc file (Note: This file has the same format as a *.zip file). A few configurations are distributed with the program. Those ending with ozi should be used with a registered version of OziExplorer running.

If you are going to send a configuration file to someone else then you should use Export Configuration rather than save. This will ensure that any file associations in the properties files are reset upon sending. Also the file lists are not saved.

Advanced Features

String Replacement Codes

The following string replacement codes are used in many different areas of OziPhotoTool. This may seem very complicated but it allows you to do very many nifty things.

Code Meaning Valid in HTML
&lat  The latitude of the photo (decimal degrees) **
&abslat  Absolute value of &lat **
&dlat  The latitude of the photo (in degº min' sec" format). Note that in batch processing and html generation the seconds symbol (") is replaces with two ' symbols ('') to avoid interference with other programs. **
&absdlat  Absolute value of &dlat **
&dmlat  The latitude of the photo (in dd.mmm format) **
&absdmlat  Absolute value of &dmlat **
&ddmmsslat  The absolute value of latitude of the photo (in dd mm ss format). This is the format used in EXIF GPS tags. **
&ddmmss.sslat The absolute value of latitude of the photo (in dd mm ss.ss format). This is the format used in EXIF GPS tags. This allows for greater accuracy in EXIFEdit 2.7 **
&reflat  The hemisphere reference ("N" or "S").This is the format used in EXIF GPS tags. **
&long   The longitude of the photo (decimal degrees) **
&abslong  Absolute value of &long **
&dlong  The longitude of the photo (in degº min' sec" format). Note that in batch processing and html generation the seconds symbol (") is replaces with two ' symbols ('') to avoid interference with other programs. **
&absdlong  Absolute value of &dlong **
&dmlong  The longitude of the photo (in dd.mmm format) **
&absdmlong  Absolute value of &dmlong **
&ddmmsslong    The absolute value of longitude of the photo (in dd mm ss format). This is the format used in EXIF GPS tags. **
&ddmmss.sslong The absolute value of longitude of the photo (in dd mm ss.ss format). This is the format used in EXIF GPS tags. This allows for greater accuracy in EXIFEdit 2.7 **
&reflong  The hemisphere reference ("E" or "W"). This is the format used in EXIF GPS tags **
&east  The easting of the photo (See Grid Setup) **
&north  The northing of the photo (See Grid Setup) **
&zone  The grid zone of the photo (See Grid Setup) **
&grid6  Six figure grid reference **
&grid8  Eight figure grid reference **
&grid10  Ten figure grid reference **
&alt  The altitude of the photo (in whatever units the track file was in) **
&calt  The converted altitude (essentially &alt * altConvFactor) **
&refalt  The altitude reference ("0" indicates positive alt, "1" indicated negative alt). This is the format used in EXIF GPS tags **
&abscalt  The absolute value of the converted altitude. This is the format used in EXIF GPS tags **
&file  The full pathname of the photo file. **
&null  The null string (use to not include a field)  
&date  The calculated UTC date of the photo in the Delphi date format. See here for more info. Note that this is usually only used in the waypoint file for OziExplorer to read. **
&localdate  The calculated date of the photo in the Delphi date format, in the camera time zone **
&dte  The calculated date of the photo parsed using the dateString field from the waypoint properties. Note that this date has the camera time zone UTC offset applied to it. **
&utcdate  The calculated date of the photo in format dd MMM yyy HH:mm:ss. Note that this date has a UTC offset of zero. **
&utcdte  The calculated date of the photo parsed using the dateString field from the waypoint properties. Note that this date has a UTC offset of zero. **
&utctime  The calculated time of the photo in format HH mm ss. Note that this time has a UTC offset of zero. This is the format used in EXIF GPS tags. **
&tkaftfile  The full name of the track file that contained the closest track point before the image (time wise) **
&tkforefile  The full name of the track file that contained the closest track point after the image (time wise) **
&tkdat  The datum of the track file **
&cr  Inserts a new line character. Used for separating comment lines of map features or creating multiple lines in watermarks.  
&num  The number of the photo successfully processed in a generation event **
&nm4  The number of the photo successfully processed in a generation event truncated to 4 digits **
&offsetnum  The number of the photo successfully processed in a generation event plus the general property numOffset **
&offsetnm4 The number of the photo successfully processed in a generation event plus the general property numOffset truncated to 4 digits **
&wmfile  The full pathname of the watermarked file created  
&fnme  The filename of the photo (without path) **
&fnmx  The filename of the photo without extension **
&fnm6  The last six characters of the filename without extension. **
&course  The true heading in the direction of the track for where the photo was taken (see the property bearingoffset below to use magnetic heading)  
&speed  The speed of the track for where the photo was taken (default in meters per second - use the property speedfactor to convert to other units)  
&dist  The distance from the photo waypoint browser filter location to this point **
@@map  The filename of the map file image saved for HTML generation through the OziExplorer interface. This map may or may not be cropped as described in the general settings. **
@@pointX  The x coordinate on a map file image that relates to a particular waypoint location. This is normally used in HTML generation **
@@pointY  The y coordinate on a map file image that relates to a particular waypoint location. This is normally used in HTML generation **
&metadataDIRECTORY.Tag& Extracts the metadata from an image if available in the form DIRECTORY.Tag. If the image metadata does not contain this tag in the appropriate directory it returns an empty string. To determine which Directories and Tags are valid use the internal image preview to have a look at one of your images. NOTE:  You must include the & at the end of the tag. **
@@imgheight The height of the image in pixels (works in HTML/KMZ generation only) **
@@imgwidth The widht of the image in pixels (works in HTML/KMZ generation only) **
@@thumbheight The height of the thumbnail image in pixels (works in HTML/KMZ generation only) **
@@thumbwidth The widht of the thumbnail image in pixels (works in HTML/KMZ generation only) **
@@wptdescription Used to access to the description field in a waypoint file. You would use this when creating custom templates for generating HTML or KML output, or for customising the PhotoWayPoint browser. It is not relevant to generating a waypoint file, only when OziPhotoTool reads from it. (works in HTML/KMZ generation only) **

Notes:
1.    @@ instead of & may be used in any of the above text replacement codes. This is the default used in html/kmz generation. You can alter this in the General Properties area (htmlStringRepChar)
2.    Only those codes that are marked with ** can be used in the photo waypoint browser and in html/kmz generation.

Track Related String Replacement Codes

For KML Generation there are some special String Replacement codes that are used to specify track point information. These are summarised in the table below. They should only be used for KML generation.

Code Meaning
@@tklat The latitude of the trackpoint (decimal degrees)
@@tkabslat Absolute value of @@tklat
@@tkdlat The latitude of the trackpoint (in degº min' sec" format). Note that in batch processing and html generation the seconds symbol (") is replaces with two ' symbols ('') to avoid interference with other programs.
@@tkabsdlat Absolute value of @@tkdlat
@@tkdmlat The latitude of the trackpoint (in dd.mmm format)
@@tkabsdmlat Absolute value of @@tkdmlat
@@tkddmmsslat The absolute value of latitude of the trackpoint (in dd mm ss format). This is the format used in EXIF GPS tags.
@@tklong  The longitude of the trackpoint (decimal degrees)
@@tkabslong Absolute value of @@tklong
@@tkdlong The longitude of the trackpoint (in degº min' sec" format). Note that in batch processing and html generation the seconds symbol (") is replaces with two ' symbols ('') to avoid interference with other programs.
@@tkabsdlong Absolute value of @@tkdlong
@@tkdmlong The longitude of the trackpoint (in dd.mmm format)
@@tkabsdmlong Absolute value of @@tkdmlong
@@tkddmmsslong   The absolute value of latitude of the trackpoint (in dd mm ss format). This is the format used in EXIF GPS tags.
@@tkalt The altitude of the trackpoint (in whatever units the track file was in)
@@tkcalt The converted altitude (essentially @@tkalt * altConvFactor)
@@tkabscalt The absolute value of the converted altitude. This is the format used in EXIF GPS tags
@@tkdte The date of the trackpoint parsed using the dateString field from the waypoint properties. Note that this date has the camera time zone UTC offset applied to it.
@@tkutcdate The date of the trackpoint in format dd MMM yyy HH:mm:ss. Note that this date has a UTC offset of zero.
@@tkutcdte The date of the trackpoint parsed using the dateString field from the waypoint properties. Note that this date has a UTC offset of zero.
@@tkutctime The  time of the trackpoint in format HH mm ss. Note that this time has a UTC offset of zero. This is the format used in EXIF GPS tags.
   

Custom String Replacement Codes

Click File|CustomStrings to add and edit custom strings. The Custom String code will be replaced with the Custom String value anytime the String Replacer is used (watermarking, waypoint file generation, HTML generation, etc.) Note that the String Replacement character should be omitted from the Custom String Dialog however it must be included in HTML templates etc. Custom String codes are saved with configuration files.

Text Output

There is a text output of the progress of OziPhotoTool in the big window. This is mostly used for debugging and trying to sort out what is going on.

General Properties

Click File, General Properties to get a dialog to change some general properties of the program. The properties you can change are.

Property Meaning Default Value
open_delay The delay in milliseconds after the call to open OziExplorer before continuing. Use this if OziExplorer has to load up large maps etc. 1000
time_delta The time added to each image (in seconds) before comparing it to the track (see below). Note that this will override whatever is calculated in the time delta manager. 0.0
imageexifdate If true OziPhotoTool will use the EXIF date to determine the time of the image. If false it will use the time the image file was last modified. This can be used for some older digital cameras that do not store EXIF information with the images, but create .jpg files for each image. true
internal_preview Determines if OziPhotoTool uses an internal preview pane to preview images, or sends the image to windows for it to open in the default image browser. If true OziPhotoTool will use the internal preview. true
browserString Used to customize the display to the right of each thumbnail in the photo waypoint browser. PhotoWaypoint Properties\:&crFile> &file&crDate> &utcdate&crLat> &dlat&crLong> &dlong&crDist> &dist

 

earthRadius Used for great circle calculations to determine distance, speed and heading between various points. By varying the units here the distance and speed values will change (the default is meters) 6366710
bearingOffest Value added to each heading calculated. Use if you want to offset each heading value by a constant amount - such as a magnetic variation 0
speedFactor Factor to multiply speed (in m/s) by to get &speed. Use if you want to change units 1
thumbSize The size of the largest side of the thumbnails generated for html/kml output 300
save_html_map If true then OziPhotoTool will attempt to save the current map loaded in OziExplorer when generating html. For this to work OziExplorer must be registered, open and must be at least version 3.95.3e. true
crop_html_map If true and save_html_map is also true then the saved map will be cropped crop_html_map_X and crop_html_map_Y pixels away from the box that bounds all waypoints that meet the filter conditions in the PhotoWaypoint browser. The cropped map has the same name as the saved map. true
crop_html_map_X The distance in pixels to the left and right of included waypoints that the saved map will be cropped.  100
crop_html_map_Y The distance in pixels to the top and bottom of included waypoints that the saved map will be cropped.  100
html_map_name The file name of the map to be saved when generating html output. images/map.png
browseNumImg The number of images displayed at one time by the Photo Waypoint Browser 5
altConvFactor A factor applied to the altituide before displaying using &calt. Altituide in OziExplorer waypoint files are by default stored in feet. To display in different units use &calt insted of &alt. The default value will convert to meters. 0.3048
dateString The date format used with &dte. For more information on how these date formats are parsed see javadocs here dd MM yyy HH:mm:ss ZZZZ
embedThumbnail If true a thumbnail will be created and embedded in the APP0 (JFIF) marker segment of the watermarked image. This greatly speeds up loading of the image in the photowaypoint browser. true
wptStringRepChar The character sequence used at the start of string replacement codes for Waypoint File generation &
htmlStringRepChar The character sequence used at the start of string replacement codes for HTML generation @@
useEmbedGPSCoord Rudimentary support to get location information from images with GPS information already embedded in EXIF data rather than from track files as part of the generation step. Use in conjunction with the next field. Note that this feature is not fully tested and some string replacement codes may not work. false
EmbedGPSDatum The datum to be recorded in the waypoint file when getting location information directly from images. WGS 84
resizeImageSize Specifies the size in pixels of the longest edge of the image to be resized as part of generation. 500
mapZoomFactor Specifies the zoom multiple for maps saved from OziExplorer as part of HTML generation. 1
resetOffsetNum If false (unchecked) will add the number of successful images processed in a generation to numOffset false
numOffset The number added to the number of successful images processed in a generation event 0
kmzFullImageCopy If true then the full image will be copied to the kmz output in the directory images/. Note that it is zipped up in the kmz file. false
kmzThumbImageCopy If true then a thumbnail will be generated and copied to the kmz output file in the directory images/. Note that it is zipped up in the kmz file. The size of the thumbnail is controlled by the property thumb size. true
replaceComma Remove and/or replace comma's from values that are returned from string replacement codes. In general you would use this feature to deal with custom image metadata that contains commas. If you do not get rid of the commas then your waypoint file may be screwed up. false
replaceCommaString The value the comma is replaced with.  
exifutils_other_date When using 'other' files you might like to use the exif tag to detemine the image time, rather than the time the file was last modified. This should work with TIFF files, Canon RAW, Nickon RAW, Minolta RAW, etc. You MUST have exiflist.exe (from exif utils) in your util directory (where exifedit.exe is). Make sure to download the latest version of exifutils from http://www.hugsan.com/EXIFutils false

Grid Setup Properties (in the General Properties area)

The following properties control the grid setup. Redfearns formula (see http://www.ga.gov.au/nmd/geodesy/datums/calcs.jsp ) is used for the latitude and longitude to grid conversion. The default settings will calculate UTM coordinates using the parameters for the WGS84 ellipsoid. If your track file is in a datum other than WGS84 you will need to enter appropriate ellipsoidal parameters (semi major axis and inverse flattening). You can set the datum of your track file in the OziExplorer configuration area (Data File Datum) See the Datums|Adding User Datums area of the OziExplorer help file for details of these parameters, you need to know what ellipsoid your datum uses. You must also ensure that the grid parameters (false easing, false northing, central scale factor, zone width and zone one meridian) are set to match your particular grid.

Property Meaning Default Value (UTM projection on WGS84 ellipsoid in the southern hemisphere)
sMajorAxis semi major axis of the reference ellipsoid 6378137.0
invFlat inverse flattening of the reference ellipsoid 298.257223563
falseEast false easting for each grid zone 500000.0
falseNorth false northing for each grid zone 10000000.0  (Use 0.0 for the Northern Hemisphere)
centScaleFact central scale factor 0.9996
zoneWidth the width in degrees of each zone 6.0
zoneOneMeridian the central meridian of zone one -177.0

 
Time Delta

Working out times is the most confusing part of using OziPhotoTool. It is advisable to use the Time Delta Manager to set the time delta as this will most likely work. First a few facts as they are currently understand.

Camera Time - The Camera time, and the time stored in the EXIF information contains no UTC offset information.

GPS Time - The time displayed on the GPS unit normally has a UTC offset associated with it. This is just the time displayed on the GPS screen. Most GPS store the time of track points in UTC regardless of what is displayed on the screen. The UTC that the GPS knows is probably more accurate than what is in the camera so this is the time associated with photos. The GPS time is taken as the "real" time.

Track Point Time - In all situations encountered so far the track point time that is downloaded from the GPS then saved in an OziExplorer track file has a UTC offset of zero. Currently there is no setting if the times of the track points are in something other than UTC. If you find this is the case you can manually alter the time delta to account for it.

Waypoint Time - The time associated with OziExplorer waypoints is in "local" time. This is what OziExplorer expects when it displays time correctly. By default OziPhotoTool outputs times with a UTC offset of zero.

Time Delta Calculation - The time delta is calculated by the time delta GUI. The camera time in UTC is first calculated by determining the image time from the raw EXIF information and applying the UTC offset entered by the user. The GPS time in UTC is determined by the user entering the date, time, and offset of the time displayed in the image selected. The time delta is the GPS time in UTC, minus the Camera time in UTC. The units of the time delta are seconds. The time delta can be manually set using the General Properties.

Waypoint Location Determination - The time delta is applied when generating output. First the raw image time is read and the camera UTC offset from the Time Delta GUI applied to get the image time in UTC. Next the time delta is added to the image time to get the "real" image time. This "real" image time is then used for comparison against each of the track point times and the location determined by linear interpolation between the closest time above and below.

Command Line Support

OziPhotoTool has a basic ability to generate a waypoint file in a non-GUI mode from the command line. To use this feature execute oziphoto.OziPhotoMain with the command line parameter g. A typical command line in a batch file would be:

java -mx128m -cp .;./jars/oziphoto.jar;./jars/metadata-extractor-2.2.2.jar oziphoto.OziPhotoMain g

Note that this is the equivalent of pressing the generate button with the settings as they last appeared in the GUI. Advanced users may experiment with editing the *.ini and *.opt files to fully customize calling from the command line. This line assumes that you have a properly installed Java Virtual Machine and that it is called from the OziPhotoTool install directory.

Other Questions

A few other questions that have been asked and some answers.

It does not work, what is wrong? Make sure you ensure the following:
- You have an up to date version of OziExplorer
- You have a 1.4 compatible Java Virtual Machine and it is the one OziPhotoTool is using, OR you have installed the full version that includes a JVM
- You reset the properties to their original settings (see above)

If that does not work copy the output and send it to me and I will try to help.

I use the OziAPI for XXX. Will OziPhotoTool stuff that up? OziPhotoTool has its own copy of the OziAPI. It refers to the one in the oziphototool install directory. So the answer is no.

Acknowledgements

The assistance and advice of Des Newman and Alan Brandon from the OziExplorer team is appreciated. Without their excellent product OziPhotoTool would not exist. Drew Noakes is recognized for his contribution of the MetadataExtractor library to the Java community. Hugh Thomas from www.hugsan.com is thanked for his permission to include exifedit.exe with the distribution of OziPhotoTool.

Please send comments to support@oziphototool.com