Jdatestamp User Guide

This section gives examples of the features in Jdatestamp and a command reference at the end.

Date Format

Processing Multiple Files

Stamping Picture Comments

Choosing the Color of Date Text

Setting Point Size of Text

Changing the Font

Location of the Date text

Vertical orientation of the Date text

Command Reference

Date Format

With release 1.1 all the options except the input and output files are defaulted to give usable results.

You may however wish to change the default date format which is a bit verbose. For this you can refer the Date Format Helper page to get the -datefmt option for the date format you desire. For example for a date text like Fri 10/1/04, 2:48 pm you can use the below command:

jdatestamp -datefmt "%a @m/@d/%y, @h:%M %pl" -outfile your_output_file.jpg your_input_file.jpg

You can default your preferred date format and also other options in the jdstmprc.txt file in the Jdatestamp installation and also in ~/.jdstmprc (Which overrides values in jdstmprc.txt) in UNIX so that you do not have to type them every time.

Processing Multiple Files

You can process multiple input files. You can either type out the individual files at the end or you can use a wild card to process all jpeg files in a directory. You can also create a file containing a list of files and pass that prefixed with a @

The tag @f can be used instead of the output file name in the -outfile option to refer to the name of the currently processed input file.

The below example stamps all .jpg files under "C:\My Documents\photos" and stores the output in "C:\stamped_photos":

jdatestamp -datefmt "%a @m/@d/%y, @h:%M %pl" -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"

You can also stamp the input files directly without copying the output using the @F tag. Be sure that you want to do this before running the command since it will date stamp the files irreversibly. The below example command stamps all the photos in the directory "C:\for_prints" overwriting them:

jdatestamp -outfile @F "C:\for_prints\*.jpg"

Stamping Picture Comments

If you have short comments describing your pictures you can stamp them along with the date using @C or @I tags in the datefmt. Jdatestamp only picks the first comment line. If your album software does not have the feature of entering comments you can do so through jhead.

Below are two examples to include the picture comments:

jdatestamp -datefmt "@C:%a @m/@d/%y, @h:%M %pl" -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"
jdatestamp -datefmt "%a @m/@d/%y, @h:%M %pl@I2, " -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"

In the first example The comment is prefixed before the date with a ':'. If the picture has a comment Florida the the stamped text is like: Florida:Fri 10/1/04, 2:48 pm. In case a picture does not have a comment the the ':' is not included in the stamped text.

In the second example the comment is added after the date text and ', ' is appended to it like: Fri 10/1/04, 2:48 pm, Florida. 2 is added after @I to indicate that the 2 characters (comma and blank) following the tag are to be added if there is a comment and skipped otherwise. @C: in the first example is the short form of @C1:.

Choosing the Color of Date Text

By default Jdatestamp uses one of the colors in the autocolors.txt file in the installation directory based on the background in the image. This corresponds to -color auto. You may like to choose a different color manually for some or all of your pictures. For this you can either specify the name of the color from this list, or specify the RGB values as colon separated values or in hex format. Below are 3 examples:

jdatestamp -color red -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"
jdatestamp -color 100:240:100 -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"
jdatestamp -color 0xFF00FF -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"

Setting Point Size of Text

Below are 2 examples of setting the Pointsize using absolute and relative pointsize:

jdatestamp -pointsize 40 -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"
jdatestamp -pointsize 40x -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"

In the second case the pointsize is 40 for a 2 megapixel (1200x1600) image. However for higher or lower image dimensions the actual pointsize used is scaled relative to a 2 megapixel image. This would result in the same relative size. It is better to use relative settings because you can use the same settings for a picture from a different camera, say from a friend.

Changing the Font

From version 1.1 Jdatestamp binary releases include a font file (VeraBI.ttf) which is used as the default font.

You can however specify your own font. Font names are not recognized. You have to give a font file. Example:

jdatestamp -font "C:\WINNT\Fonts\georgiaz.ttf" -pointsize 50x -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"

To find a windows font file name right click on the file and choose properties.

Location of the Date text

You can change the location of the date text using -x and -y options. You can specify an absolute or relative pixel value for these or a % value. Negative pixel values are measured from the right and bottom edge of the image.

You can also use the aliases left, right, or center for the option -x and top, bottom, or center for the option -y. left and top are the same as 80x and right and bottom are the same as -80x. center is the same as 50%.

Note that the Jdatestamp defaults for -x and -y are -100x which is slightly more than -80x corresponding to right and bottom.

Examples:

jdatestamp -x center -pointsize 50x -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"
jdatestamp -x -150 -y 75% -pointsize 50x -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"
jdatestamp -x 80x -y top -pointsize 50x -outfile "C:\stamped_photos\@f" "C:\My Documents\photos\*.jpg"

Vertical orientation of the Date text

In case of picture taken with a vertical camera the stamped text can be rotated. The below example stamps the vertical picture file list entered in the file vertical_pics.txt and stores them in stamped_photos:

jdatestamp -rotate 90 -outfile "C:\stamped_photos\@f" "@C:\vertical_pics.txt"

In case your camera has a gravity sensor to detect a vertical camera you can omit this option or pass auto and the angle will be read from the EXIF.

Command Reference

jdatestamp [optional-switches] -outfile fileName -font Font file -pointsize pointsize inputfile[...]

Open a Windows command prompt or MSYS prompt if you have it installed and Type jdatestamp or jdatestamp -h for command line options. Below is similar information with some more details.

You can specify any of the switches for the program in the jdstmprc.txt file in the Jdatestamp installation. This file is present in the installation with commented examples. The options specified in this file serve as program defaults. In case of UNIX these can be overridden by personal default values in ~/.jdstmprc. These are overridden by the command line arguments. The program/personal default values are listed in the program usage as (Your Default for this option: <value>). You can clear the default for any argument by passing --, -font -- for example. This would cause the Jdatestamp default to be used. You can clear all default argument by passing -- as the first argument to jdatestamp.

On Windows you can use either forward slash "/" as or backward slash "\" for directory paths unless you are using MSYS.

inputfile[...] Input Jpeg file(s). You can specify the file(s) as one or more of the following:

Jpeg File
@<file containing a file list one on each line>. For example @/home/msuresh/fileList
On windows you can specify a wildcard file pattern. Use ** to recurse into subdirectories, example: "c:\my photos\**\*.jpg"
On unix wild cards are handled by the shell. However if you want to recurse into a directory use the zsh shell which supports recursive wildcards (**) or use find utility to get a list of files using a command like:
find ~/myphotos -name '*.jpg' > fileList

Below is an example specifying an input file and file list:
jdatestamp <required options> photo.jpg @C:\temp\pictureList.txt

Switches:

-outfile fileName Output File. The following placeholders are useful in case of multiple input files:
@f: Input File Name, @p: File Name Prefix
@s: File Name Suffix with the '.'
@d[n]: Input file directory including the trailing /. If n is supplied n directory prefixes are skipped
@F[n]: Input File path. If n is supplied n directory prefixes are skipped
Examples:
jdatestamp <other options> -outfile dated_photo.jpg myphoto.jpg
The below command processes all pictures under "C:\my photos" directory and puts them under C:\newimages directory with the same directory structure:

jdatestamp <other options> -outfile C:\newimages\@d2@f "c:\my photos\**\*.jpg"

-datefmt Format String Format String similar to strftime C function. Common strftime options:
%d: Date, %m: Month number, %y/%Y: 2/4 digit year
%a/%A: short/full Week name,
%I/%H: Hour in 12/24 hour fmt, %M: minute, %S: seconds,
%b/%B: short/full Month Name, %p: AM/PM text.
In addition the below jdatestamp extensions are available:
@d: Date without leading zeroes
@m: Month number without leading zeroes
@h/@H: Hour in 12/24 hour format without leading zeroes
@M: Minute without leading zeroes
@s: Seconds without leading zeroes
@x/@X: Appropriate number suffix in lowercase/uppercase for the date, which is st, nd, rd or th as in 2nd or 10th
@p/@P: AM/PM text in lowercase/uppercase with a period('.') like a.m.
@c: 1st line of the image comment section if present.
@C[n]<nchars>: Similar to @c but n (n=1 if omitted) following characters are skipped if there no comment section in the image, example '@C2: '.
@I[n]<nchars>: Similar to @C but but the n chars are prefixed to the comment instead of suffixing.
@f: Input Image File Name.
@n: Input Image File Name without the suffix.
Also you can follow the strftime options %a, %A, %b, %B and %p with a l or u to convert it to lowercase or uppercase respectively.
For example
-datefmt "Date: @d@X %bu %Y, @h:%M:%S %pl"
produces an output like:
Date: 18TH MAR 2004, 2:09:14 pm
The default is for a date text like Sat Aug 7 2004, 2:48 am, i.e "%a %b @d %Y, @h:%M %pl".

left|right|center|[+|-]pixels[x]
|[+|-]n% X Pixel location of top left corner of date from top left corner of image. A negative value specifies the x distance of the bottom right corner of the date from the bottom right corner of the image. If the position is followed by x then the value is scaled relative to a 2 megapixel image. If a % is specified it specifies the % of space to the left of date text. left is same as 80x, right as -80x and center as 50%.

-y top|bottom|center||[+|-]pixels[x]
|[+|-]n% Y Pixel location of date text. See description of -x option for more info.

If an angle is specified through -rotate option or present in EXIF, -x and -y options are applied relative to the upright image. For example for options:
-x right -y bottom -rotate 90
The text is rotated clockwise -90 degrees (i.e 90 degrees counter-clockwise) and the vertical text is on the top right corner. Now when the output image is rotated 90 degrees clockwise to make it upright the date text is upright at the bottom right corner as expected from the -x and -y option values.
If the x or y location causes the date text to go out of the image the value is adjusted so that the date text is "pushed" inside the image.
Also the x and y coordinates are rounded to the nearest JPEG DCT boundary (Usually 8, 16 or 24 pixels) to enable lossless crop/drop
Examples:
-x 500 -y 200 positions the date text at location (500, 200) pixels from top left of image.
-x -64x y 50% positions the date at center-right of the image leaving 64 pixels from the right edge for a 2 megapixel (1200x1600) image. For other image dimensions 64 is multiplied by the scaling factor to give the same relative spacing.
-x 90% -y -5% positions the image at the bottom right. -5% is the same as 95%.

-rotate auto|[+|-]0|90|180|270 Specifies the clockwise angle the image should be rotated to make it upright. The text is rotated and positioned so that when the output image is made upright the date text is upright and positioned according to the -x and -y arguments if present. The image itself is not rotated. If auto is specified for this option then the angle is read from the EXIF header. The angle information is correctly set in the EXIF if the camera has a gravity sensor to detect camera angle, otherwise it would be 0. The default for this option is auto.

-tmpdir tmpDir Temporary Directory to be used. Defaults to /tmp (C:/temp for Windows)

-color auto|color_name|R:G:B|0x<hexval> Color of date text specified as either auto for auto color assignment based on background or the color name or Red Green Blue components each ranging from 0-255 or as a 6 digit (24 bit) hex value. jdatestamp looks in the colors.txt file in the installation to convert the color-name specified to RGB and gives an error if it cannot find the color-name specified. The default is auto.
Examples:
-color auto
-color magenta
-color lightgreen
-color 218:112:214
-color 0xDA70D6

-trans 0-100 Transparency of text. The Default is 0 which means the text is opaque.

-bgcolor color_name|R:G:B|0x<hexval> Color of background. The default is yellow. Note that one of the options -bgcolor, -bgtrans, -bginset must be used for a background

-bgtrans 0-100 Transparency of background. The Default is 60.

-bginset pixels[x][:yPixels[x]] Background inset in absolute or relative pixels if followed by an x. Inset in y direction can be specified separately if desired.
Examples -bginset 4, -bginset 3.5x, -bginset 3x:2x.
The default is 5x

-bordercolor color_name|R:G:B|0x<hexval> Color of Border. The default is red. Note that one of the options -bordercolor, -bordertrans, -borderwidth must be used for a border

-bordertrans 0-100 Transparency of background. The Default is 0.

-borderwidth pixels[x][:yPixels[x]] Border width in absolute or relative pixels. See -bginset option for examples. The default is 5x

-timeofs [+|-] [[[days:]hrs:]mins:]sec Offset time to be added (Subtracted if prefixed with -) to picture time.
Examples:
-timeofs 30 adds 30 seconds which rounds the time to the closest minute
-timeofs -1:0:0 reduces 1 hour

-font Font file Path to a scalable font file like True Type (.ttf file) or Postscript (.pfb file). The Default is the font file (VeraBI.ttf) in jdatestamp installation.
Example:
-font C:/Windows/fonts/VERDANAB.TTF

-fontmetric Font Metric file Path to the Font Metric File for font formats like postscript where font metrics are in a separate file. For .pfb/.pfa font files it defaults to the corresponding .afm/.pfm file if present.
Example:
-fontmetric C:/myfonts/fonts/n019024l.afm

-pointsize pointsize[x] Point Size. If followed by x the actual pointsize is scaled relative to a 2 megapixel image so that the relative text size is the same. The Default is 47x.
Examples:
-pointsize 50
-pointsize 35.5x.

-time ctime|mtime|atime|systime|"yyyy:mm:dd[ HH:min:ss]" Time to be stamped in case Exif time information is not available.
Possible values: ctime/mtime/atime: File Creation/Modification/Access time.
systime: Current system time. The same time is used for all files.
"yyyy:mm:dd[ HH:min:ss]": Actual time value
The Default is ctime

-usetime never|backupwarn|backup|override Specifies When -time option should be used.
Possible values:
never: -time Option is not used and jdatestamp gives an error if Exif time is not available.
backupwarn: -time Option is used as a backup if Exif time is not available and a warning message is printed.
backup: Same as backupwarn but no warning message is printed.
override: -time option is used and Exif time is ignored if present.
The Default is backupwarn

-keepfiletime yes|no Specifies if the output file timestamp is to be set to that of the input file stamp. The default is to do so when the file ctime/mtime/atime is used for stamping

-debug 0-5 Sets the debug level for messages printed. Values are:
0: No Messages except for those coming from jhead/jpegtran
1: Only Error Messages
2: Error and Warning Messages
3: Error, Warning and Informational Messages
4: All messages including debug messages
5: Intermediate files do not have PID appended and are not deleted in addition to 4 above.
The Default is 3.

-listcolors Lists names of available colors along with their values in R:G:B and hex format. Other options are ignored. You can also refer the colors.html file for this.

-copyexif yes|no Specifies if the Exif header is to be copied to output. The default is yes.

-gencolors Generates the colors.html file. Uses the -outfile option if supplied, otherwise creates the colors.html file in the current directory.

-mkdir yes|no Specifies if directories should be created for outfile. If this is no you will get an error if the directory for the output file does not exist. The Default is Yes.

-text Text Write Text instead of date. -datefmt and -timeofs options are ignored. You can use -datefmt option also for this purposes but you have to escape the @'s and %'s in your text so that they are not interpreted.

Home Installation User Guide Technical Info

inputfile[...]	Input Jpeg file(s). You can specify the file(s) as one or more of the following: Jpeg File @<file containing a file list one on each line>. For example @/home/msuresh/fileList On windows you can specify a wildcard file pattern. Use to recurse into subdirectories, example: "c:\my photos\*\.jpg" On unix wild cards are handled by the shell. However if you want to recurse into a directory use the zsh shell which supports recursive wildcards () or use find utility to get a list of files using a command like: *find ~/myphotos -name '.jpg' > fileList** Below is an example specifying an input file and file list: jdatestamp <required options> photo.jpg @C:\temp\pictureList.txt
Switches:
-outfile fileName	Output File. The following placeholders are useful in case of multiple input files: @f: Input File Name, @p: File Name Prefix @s: File Name Suffix with the '.' @d[n]: Input file directory including the trailing /. If n is supplied n directory prefixes are skipped @F[n]: Input File path. If n is supplied n directory prefixes are skipped Examples: jdatestamp <other options> -outfile dated_photo.jpg myphoto.jpg The below command processes all pictures under "C:\my photos" directory and puts them under C:\newimages directory with the same directory structure: jdatestamp <other options> -outfile C:\newimages\@d2@f "c:\my photos\*\.jpg"
-datefmt Format String	Format String similar to strftime C function. Common strftime options: %d: Date, %m: Month number, %y/%Y: 2/4 digit year %a/%A: short/full Week name, %I/%H: Hour in 12/24 hour fmt, %M: minute, %S: seconds, %b/%B: short/full Month Name, %p: AM/PM text. In addition the below jdatestamp extensions are available: @d: Date without leading zeroes @m: Month number without leading zeroes @h/@H: Hour in 12/24 hour format without leading zeroes @M: Minute without leading zeroes @s: Seconds without leading zeroes @x/@X: Appropriate number suffix in lowercase/uppercase for the date, which is st, nd, rd or th as in 2nd or 10th @p/@P: AM/PM text in lowercase/uppercase with a period('.') like a.m. @c: 1st line of the image comment section if present. @C[n]<nchars>: Similar to @c but n (n=1 if omitted) following characters are skipped if there no comment section in the image, example '@C2: '. @I[n]<nchars>: Similar to @C but but the n chars are prefixed to the comment instead of suffixing. @f: Input Image File Name. @n: Input Image File Name without the suffix. Also you can follow the strftime options %a, %A, %b, %B and %p with a l or u to convert it to lowercase or uppercase respectively. For example -datefmt "Date: @d@X %bu %Y, @h:%M:%S %pl" produces an output like: Date: 18TH MAR 2004, 2:09:14 pm The default is for a date text like Sat Aug 7 2004, 2:48 am, i.e "%a %b @d %Y, @h:%M %pl".
left\|right\|center\|[+\|-]pixels[x] \|[+\|-]n%	X Pixel location of top left corner of date from top left corner of image. A negative value specifies the x distance of the bottom right corner of the date from the bottom right corner of the image. If the position is followed by x then the value is scaled relative to a 2 megapixel image. If a % is specified it specifies the % of space to the left of date text. left is same as 80x, right as -80x and center as 50%.
-y top\|bottom\|center\|\|[+\|-]pixels[x] \|[+\|-]n%	Y Pixel location of date text. See description of -x option for more info.
If an angle is specified through -rotate option or present in EXIF, -x and -y options are applied relative to the upright image. For example for options: -x right -y bottom -rotate 90 The text is rotated clockwise -90 degrees (i.e 90 degrees counter-clockwise) and the vertical text is on the top right corner. Now when the output image is rotated 90 degrees clockwise to make it upright the date text is upright at the bottom right corner as expected from the -x and -y option values. If the x or y location causes the date text to go out of the image the value is adjusted so that the date text is "pushed" inside the image. Also the x and y coordinates are rounded to the nearest JPEG DCT boundary (Usually 8, 16 or 24 pixels) to enable lossless crop/drop Examples: -x 500 -y 200 positions the date text at location (500, 200) pixels from top left of image. -x -64x y 50% positions the date at center-right of the image leaving 64 pixels from the right edge for a 2 megapixel (1200x1600) image. For other image dimensions 64 is multiplied by the scaling factor to give the same relative spacing. -x 90% -y -5% positions the image at the bottom right. -5% is the same as 95%.
-rotate auto\|[+\|-]0\|90\|180\|270	Specifies the clockwise angle the image should be rotated to make it upright. The text is rotated and positioned so that when the output image is made upright the date text is upright and positioned according to the -x and -y arguments if present. The image itself is not rotated. If auto is specified for this option then the angle is read from the EXIF header. The angle information is correctly set in the EXIF if the camera has a gravity sensor to detect camera angle, otherwise it would be 0. The default for this option is auto.
-tmpdir tmpDir	Temporary Directory to be used. Defaults to /tmp (C:/temp for Windows)
-color auto\|color_name\|R:G:B\|0x<hexval>	Color of date text specified as either auto for auto color assignment based on background or the color name or Red Green Blue components each ranging from 0-255 or as a 6 digit (24 bit) hex value. jdatestamp looks in the colors.txt file in the installation to convert the color-name specified to RGB and gives an error if it cannot find the color-name specified. The default is auto. Examples: -color auto -color magenta -color lightgreen -color 218:112:214 -color 0xDA70D6
-trans 0-100	Transparency of text. The Default is 0 which means the text is opaque.
-bgcolor color_name\|R:G:B\|0x<hexval>	Color of background. The default is yellow. Note that one of the options -bgcolor, -bgtrans, -bginset must be used for a background
-bgtrans 0-100	Transparency of background. The Default is 60.
-bginset pixels[x][:yPixels[x]]	Background inset in absolute or relative pixels if followed by an x. Inset in y direction can be specified separately if desired. Examples -bginset 4, -bginset 3.5x, -bginset 3x:2x. The default is 5x
-bordercolor color_name\|R:G:B\|0x<hexval>	Color of Border. The default is red. Note that one of the options -bordercolor, -bordertrans, -borderwidth must be used for a border
-bordertrans 0-100	Transparency of background. The Default is 0.
-borderwidth pixels[x][:yPixels[x]]	Border width in absolute or relative pixels. See -bginset option for examples. The default is 5x
-timeofs [+\|-] [[[days:]hrs:]mins:]sec	Offset time to be added (Subtracted if prefixed with -) to picture time. Examples: -timeofs 30 adds 30 seconds which rounds the time to the closest minute -timeofs -1:0:0 reduces 1 hour
-font Font file	Path to a scalable font file like True Type (.ttf file) or Postscript (.pfb file). The Default is the font file (VeraBI.ttf) in jdatestamp installation. Example: -font C:/Windows/fonts/VERDANAB.TTF
-fontmetric Font Metric file	Path to the Font Metric File for font formats like postscript where font metrics are in a separate file. For .pfb/.pfa font files it defaults to the corresponding .afm/.pfm file if present. Example: -fontmetric C:/myfonts/fonts/n019024l.afm
-pointsize pointsize[x]	Point Size. If followed by x the actual pointsize is scaled relative to a 2 megapixel image so that the relative text size is the same. The Default is 47x. Examples: -pointsize 50 -pointsize 35.5x.
-time ctime\|mtime\|atime\|systime\|"yyyy:mm:dd[ HH:min:ss]"	Time to be stamped in case Exif time information is not available. Possible values: ctime/mtime/atime: File Creation/Modification/Access time. systime: Current system time. The same time is used for all files. "yyyy:mm:dd[ HH:min:ss]": Actual time value The Default is ctime
-usetime never\|backupwarn\|backup\|override	Specifies When -time option should be used. Possible values: never: -time Option is not used and jdatestamp gives an error if Exif time is not available. backupwarn: -time Option is used as a backup if Exif time is not available and a warning message is printed. backup: Same as backupwarn but no warning message is printed. override: -time option is used and Exif time is ignored if present. The Default is backupwarn
-keepfiletime yes\|no	Specifies if the output file timestamp is to be set to that of the input file stamp. The default is to do so when the file ctime/mtime/atime is used for stamping
-debug 0-5	Sets the debug level for messages printed. Values are: 0: No Messages except for those coming from jhead/jpegtran 1: Only Error Messages 2: Error and Warning Messages 3: Error, Warning and Informational Messages 4: All messages including debug messages 5: Intermediate files do not have PID appended and are not deleted in addition to 4 above. The Default is 3.
-listcolors	Lists names of available colors along with their values in R:G:B and hex format. Other options are ignored. You can also refer the colors.html file for this.
-copyexif yes\|no	Specifies if the Exif header is to be copied to output. The default is yes.
-gencolors	Generates the colors.html file. Uses the -outfile option if supplied, otherwise creates the colors.html file in the current directory.
-mkdir yes\|no	Specifies if directories should be created for outfile. If this is no you will get an error if the directory for the output file does not exist. The Default is Yes.
-text Text	Write Text instead of date. -datefmt and -timeofs options are ignored. You can use -datefmt option also for this purposes but you have to escape the @'s and %'s in your text so that they are not interpreted.