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