Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 173 lines (122 sloc) 5.37 kB
7457847 Tutorial updated.
Jan Friedrich authored
1 = Mini Tutorial
03f441e First approach to Tutorial
Jan Friedrich authored
2
3
4 == Installation
5
71cd1a2 Typos fixed
Jan Friedrich authored
6 * Installing the Exiftool command-line application from Phil Harvey
03f441e First approach to Tutorial
Jan Friedrich authored
7 (see http://www.sno.phy.queensu.ca/~phil/exiftool/install.html)
8 * Installing the Ruby library (<code>gem install mini_exiftool</code>)
9
10
14482c5 Tutorial updated.
Jan Friedrich authored
11 == Lesson 1: Reading Meta Data
03f441e First approach to Tutorial
Jan Friedrich authored
12
14482c5 Tutorial updated.
Jan Friedrich authored
13 === A Simple Example
03f441e First approach to Tutorial
Jan Friedrich authored
14
15 require 'mini_exiftool'
16
17 photo = MiniExiftool.new 'photo.jpg'
18 puts photo['DateTimeOriginal']
19
20
14482c5 Tutorial updated.
Jan Friedrich authored
21 === Smart Tag Names
03f441e First approach to Tutorial
Jan Friedrich authored
22 In the example above we use <code>photo['DateTimeOriginal']</code> to
23 get the value for the time the photo was taken. But tag names are not
cb89961 Some small step forward in the tutorial.
Jan Friedrich authored
24 case sensitive and additional underlines are also irrelevant. So
03f441e First approach to Tutorial
Jan Friedrich authored
25 following expressions are equivalent:
26 photo['DateTimeOriginal']
27 photo['datetimeoriginal']
28 photo['date_time_original']
29
059c14b @janfri Allow symbols for tag access via [].
authored
30 It is also possible to use symbols:
31 photo[:DateTimeOriginal]
32 photo[:datetimeoriginal]
33 photo[:date_time_original]
03f441e First approach to Tutorial
Jan Friedrich authored
34
14482c5 Tutorial updated.
Jan Friedrich authored
35 === Nicer Access Via Dynamic Methods
cb89961 Some small step forward in the tutorial.
Jan Friedrich authored
36
03f441e First approach to Tutorial
Jan Friedrich authored
37 Using the []-method is the safest way to access to values of tags
14482c5 Tutorial updated.
Jan Friedrich authored
38 (e. g. Self-timer you can only access this way) but the smarter way is
03f441e First approach to Tutorial
Jan Friedrich authored
39 using dynamic method access. You can write:
40 photo.datetimeoriginal
14482c5 Tutorial updated.
Jan Friedrich authored
41 or also
03f441e First approach to Tutorial
Jan Friedrich authored
42 photo.date_time_original
cb89961 Some small step forward in the tutorial.
Jan Friedrich authored
43
44
14482c5 Tutorial updated.
Jan Friedrich authored
45 === Value Types
cb89961 Some small step forward in the tutorial.
Jan Friedrich authored
46
47 Following types of values are at the moment supported:
76d4e41 Tutorial updated.
Jan Friedrich authored
48 * Array (e. g. Keywords => ['tree', 'gras'])
cb89961 Some small step forward in the tutorial.
Jan Friedrich authored
49 * Fixnum (e. g. ISO => 400)
059c14b @janfri Allow symbols for tag access via [].
authored
50 * Float (e. g. FNumber => 9.5)
cb89961 Some small step forward in the tutorial.
Jan Friedrich authored
51 * String (e. g. Model => DYNAX 7D)
52 * Time (e. g. DateTimeOriginal => 2005:09:13 20:08:50)
53
76d4e41 Tutorial updated.
Jan Friedrich authored
54 Be aware, if there is only one value in a tag which can hold multiple
4b0ff33 @janfri Remove implementing of to_a in serval cases, use Array method instead.
authored
55 values the result is'nt an array! But you can get one with the Array
76d4e41 Tutorial updated.
Jan Friedrich authored
56 method:
57 # only _one_ keyword
58 p1 = MiniExiftool.new 'p1.jpg'
59 p1.keywords # => 'red'
60 # _more than one_ keywords
61 p3 = MiniExiftool.new 'p3.jpg'
62 p3.keywords # => ['red', 'yellow', 'green']
63
64 # if we want to get an array in both cases and don't know
4b0ff33 @janfri Remove implementing of to_a in serval cases, use Array method instead.
authored
65 # if there is one ore more values set let's take Array()
66 Array(p1.keywords) # => ['red']
67 Array(p3.keywords) # => ['red', 'yellow', 'green']
76d4e41 Tutorial updated.
Jan Friedrich authored
68
75186d6 @janfri Update Tutorial.
authored
69 === Using options
70
cb89961 Some small step forward in the tutorial.
Jan Friedrich authored
71 The Exiftool command-line application has an option (-n) to get values
72 as numbers if possible, in MiniExiftool you can do this with setting
14482c5 Tutorial updated.
Jan Friedrich authored
73 the <code>:numerical</code> option to +true+ while generating a new
74 instance with new or using the <code>numerical=</code>-method
75 combining with calling <code>reload</code>.
76
abdc871 Documentation updated.
Jan Friedrich authored
77 Let's look at an example:
14482c5 Tutorial updated.
Jan Friedrich authored
78 # standard: numerical is false
79 photo = MiniExiftool.new 'photo.jpg'
71cd1a2 Typos fixed
Jan Friedrich authored
80 photo.exposure_time # => '1/60' (String)
14482c5 Tutorial updated.
Jan Friedrich authored
81 # now with numerical is true
82 photo.numerical = true
83 photo.reload
84 photo.exposure_time # => 0.01666667 (Float)
85 This behaviour can be useful if you want to do calculations on the
86 value, if you only want to show the value the standard behaviour is
87 maybe better.
88
76d4e41 Tutorial updated.
Jan Friedrich authored
89 The Time class of Ruby cannot handle timestamps before 1st January 1970
90 on some platforms. If there are timestamps in files before this date it
059c14b @janfri Allow symbols for tag access via [].
authored
91 will result in an error. In this case we can set the option
76d4e41 Tutorial updated.
Jan Friedrich authored
92 <code>:timestamps</code> to +DateTime+ to use DateTime objects instead
93 of Time objects.
94
95 There is another option <code>:composite</code>. If this is set to
96 +false+ the composite tags are not calculated by the exiftool
97 command-line application (option -e).
98
75186d6 @janfri Update Tutorial.
authored
99 Further options are
100 * <code>:ignore_minor_errors</code> to ignore minor
101 errors (See -m-option of the exiftool command-line application,
102 default is +false+)
103 * <code>:coord_format</code> set format for GPS coordinates (See
104 -c-option of the exiftool command-line application, default is +nil+
105 that means exiftool standard)
106 * <code>:replace_invalid_chars</code> replace string for invalid
107 UTF-8 characters or +false+ if no replacing should be done,
108 default is +false+
109
14482c5 Tutorial updated.
Jan Friedrich authored
110 === Further Example
111
112 For understanding reading access to meta data also have a look at the
113 example file <code>print_portraits.rb</code> in the +examples+
114 directory.
115
116 == Lesson 2: Writing Meta Data
117
118
119 === Also A Very Simple Example
120
121 require 'mini_exiftool'
122
123 photo = MiniExiftool.new 'photo.jpg'
124 photo.comment = 'hello world'
125 photo.save
126
127
128 === Save Is Atomar
129
130 If you have changed serval values and call the +save+-method either
131 all changes will be written to the file or nothing. The return value
132 of the +save+-method is +true+ if all values are written to the file
133 otherwise save returns +false+. In the last case you can use the
134 +errors+-method which returns a hash of the tags which values couldn't
135 be writed with an error message for each of them.
136
137
138 === Interesting Methods
139
140 Have a look at the <code>changed?</code>-method for checking if the
141 value of a specific tag is changed or a changing in general is
142 done. In the same way the +revert+-method reverts the value of a
143 specific tag or in general all changes.
144
abdc871 Documentation updated.
Jan Friedrich authored
145 You should also look at the rdoc information of MiniExiftool.
14482c5 Tutorial updated.
Jan Friedrich authored
146
a7bdffa @janfri Update documentation for using yard.
authored
147 === Further Examples
148
75186d6 @janfri Update Tutorial.
authored
149 Have a look in the examples folder of MiniExiftool.
3a8bca1 @janfri Update documentation and new example for copying meta data.
authored
150
151
152 == Lesson 3: Copying Meta Data
153
154 === Examples
155
156 require 'mini_exiftool'
157
158 photo = MiniExiftool.new('photo.jpg')
159
160 # Update the author tag of photo.jpg with the value of the author tag
161 # of another_photo.jpg
162 photo.copy_tags_from('another_photo.jpg', 'Author')
163
164 # It's also possible to use symbols and case is also not meaningful
165 photo.copy_tags_from('another_photo.jpg', :author)
166
167 # Further more than one tag can be copied at once
168 photo.copy_tags_from('another_photo', %w[author copyright])
169
170 === Further Example
171
172 Look at the file copy_icc_profile.rb in the examples folder of MiniExiftool.
Something went wrong with that request. Please try again.