1[manpage_begin jpeg n 0.3.5] 2[copyright {2004-2005, Code: Aaron Faupell <afaupell@users.sourceforge.net>}] 3[copyright {2007, Code: Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[copyright {2004-2009, Doc: Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 5[moddesc {JPEG image manipulation}] 6[titledesc {JPEG querying and manipulation of meta data}] 7[category {File formats}] 8[require Tcl 8.2] 9[require jpeg [opt 0.3.5]] 10[description] 11[para] 12 13This package provides commands to query and modify JPEG images. JPEG 14stands for [term {Joint Photography Experts Group}] and is a standard 15for the lossy compression of photographical images. It is specified at 16[uri LINK_HERE]. 17 18[section COMMANDS] 19[list_begin definitions] 20 21[call [cmd ::jpeg::isJPEG] [arg file]] 22 23Returns a boolean value indicating if [arg file] is a 24JPEG image. 25 26[call [cmd ::jpeg::imageInfo] [arg file]] 27 28Returns a dictionary with keys [const version], [const units], 29[const xdensity], [const ydensity], [const xthumb], and 30[const ythumb]. The values are the associated properties of the JPEG 31image in [arg file]. 32 33Throws an error if [arg file] is not a JPEG image. 34 35 36[call [cmd ::jpeg::dimensions] [arg file]] 37 38Returns the dimensions of the JPEG [arg file] as a list of the 39horizontal and vertical pixel count. 40 41Throws an error if [arg file] is not a JPEG image. 42 43 44[call [cmd ::jpeg::getThumbnail] [arg file]] 45 46This procedure will return the binary thumbnail image data, if a JPEG 47thumbnail is included in [arg file], and the empty string 48otherwise. Note that it is possible to include thumbnails in formats 49other than JPEG although that is not common. The command finds 50thumbnails that are encoded in either the JFXX or EXIF segments of the 51JPEG information. If both are present the EXIF thumbnail will take precedence. 52 53Throws an error if [arg file] is not a JPEG image. 54 55[example { 56 set fh [open thumbnail.jpg w+] 57 fconfigure $fh -translation binary -encoding binary 58 puts -nonewline $fh [::jpeg::getThumbnail photo.jpg] 59 close $fh 60}] 61 62[call [cmd ::jpeg::getExif] [arg file] [opt [arg section]]] 63 64[arg section] must be one of [const main] or [const thumbnail]. 65The default is [const main]. 66 67Returns a dictionary containing the EXIF information for the specified section. 68 69For example: 70[para] 71[example { 72 set exif { 73 Make Canon 74 Model {Canon DIGITAL IXUS} 75 DateTime {2001:06:09 15:17:32} 76 } 77}] 78 79Throws an error if [arg file] is not a JPEG image. 80 81[call [cmd ::jpeg::formatExif] [arg keys]] 82 83Takes a list of key-value pairs as returned by [cmd getExif] and formats 84many of the values into a more human readable form. As few as one key-value 85may be passed in, the entire exif is not required. 86 87[example { 88 foreach {key val} [::jpeg::formatExif [::jpeg::getExif photo.jpg]] { 89 puts "$key: $val" 90 } 91}] 92[para] 93[example { 94 array set exif [::jpeg::getExif photo.jpg] 95 puts "max f-stop: [::jpeg::formatExif [list MaxAperture $exif(MaxAperture)]] 96}] 97 98[call [cmd ::jpeg::exifKeys]] 99 100Returns a list of the EXIF keys which are currently understood. 101There may be keys present in [cmd getExif] data that are not understood. 102Those keys will appear in a 4 digit hexadecimal format. 103 104[call [cmd ::jpeg::removeExif] [arg file]] 105 106Removes the Exif data segment from the specified file and replaces 107it with a standard JFIF segment. 108 109Throws an error if [arg file] is not a JPEG image. 110 111[call [cmd ::jpeg::stripJPEG] [arg file]] 112 113Removes all metadata from the JPEG file leaving only 114the image. This includes comments, EXIF segments, JFXX 115segments, and application specific segments. 116 117Throws an error if [arg file] is not a JPEG image. 118 119 120[call [cmd ::jpeg::getComments] [arg file]] 121 122Returns a list containing all the JPEG comments found in 123the [arg file]. 124 125Throws an error if [arg file] is not a valid JPEG image. 126 127 128[call [cmd ::jpeg::addComment] [arg file] [arg text]...] 129 130Adds one or more plain [arg text] comments to the JPEG image 131in [arg file]. 132 133Throws an error if [arg file] is not a valid JPEG image. 134 135 136[call [cmd ::jpeg::removeComments] [arg file]] 137 138Removes all comments from the file specified. 139 140Throws an error if [arg file] is not a valid JPEG image. 141 142 143[call [cmd ::jpeg::replaceComment] [arg file] [arg text]] 144 145Replaces the first comment in the file with the new [arg text]. 146This is merely a shortcut for [cmd ::jpeg::removeComments] 147and [cmd ::jpeg::addComment] 148 149Throws an error if [arg file] is not a valid JPEG image. 150 151[call [cmd ::jpeg::debug] [arg file]] 152 153Prints everything we know about the given file in a nice format. 154 155[call [cmd ::jpeg::markers] [arg channel]] 156 157This is an internal helper command, we document it for use by advanced 158users of the package. The argument [arg channel] is an open file 159handle positioned at the start of the first marker (usually 2 160bytes). The command returns a list with one element for each JFIF 161marker found in the file. Each element consists of a list of the 162marker name, its offset in the file, and its length. The offset points 163to the beginning of the sections data, not the marker itself. The 164length is the length of the data from the offset listed to the start 165of the next marker. 166 167[list_end] 168 169[section LIMITATIONS] 170 171can only work with files 172cant write exif data 173gps exif data not parsed 174makernote data not yet implemented 175 176[section {BUGS, IDEAS, FEEDBACK}] 177 178This document, and the package it describes, will undoubtedly contain 179bugs and other problems. 180 181Please report such in the category [emph jpeg] of the 182[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 183 184Please also report any ideas for enhancements you may have for either 185package and/or documentation. 186 187 188[keywords jpeg image comment exif thumbnail jfif] 189[manpage_end] 190