doc/file.README.html in halation-0.1.0 vs doc/file.README.html in halation-0.2.0
- old
+ new
@@ -59,14 +59,224 @@
<iframe id="search_frame" src="file_list.html"></iframe>
<div id="content"><div id='filecontents'><h1>Halation</h1>
+<p><a href="https://badge.fury.io/rb/halation"><img src="https://badge.fury.io/rb/halation.svg" alt="Gem Version"></a>
+<a href="https://coveralls.io/github/amclain/halation?branch=master"><img src="https://coveralls.io/repos/github/amclain/halation/badge.svg?branch=master" alt="Coverage Status"></a>
+<a href="http://www.rubydoc.info/gems/halation"><img src="https://img.shields.io/badge/docs-api-blue.svg" alt="API Documentation"></a>
+<a href="https://github.com/amclain/halation/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellowgreen.svg" alt="MIT License"></a></p>
+
<p>Add Exif metadata to film photographs.</p>
+
+<h2>Issues, Bugs, Feature Requests</h2>
+
+<p>Any bugs and feature requests should be reported on the GitHub issue tracker:</p>
+
+<p><a href="https://github.com/amclain/halation/issues">https://github.com/amclain/halation/issues</a></p>
+
+<p><strong>Pull requests are preferred via GitHub.</strong></p>
+
+<p>Mercurial users can use <a href="http://hg-git.github.io/">Hg-Git</a> to interact with
+GitHub repositories.</p>
+
+<h2>Installation</h2>
+
+<p>Halation is available as a Ruby gem.</p>
+
+<ol>
+<li><p>Install <a href="https://www.ruby-lang.org">Ruby</a> 2.1 or higher.</p>
+
+<ul>
+<li>Windows: Use <a href="http://rubyinstaller.org/downloads/">RubyInstaller</a>.</li>
+<li>Mac: Use <a href="https://www.ruby-lang.org/en/documentation/installation/#homebrew">homebrew</a>.</li>
+<li>Linux: Use <a href="https://github.com/sstephenson/rbenv#basic-github-checkout">rbenv</a>.</li>
+<li><a href="https://www.ruby-lang.org/en/documentation/installation">Additional installation instructions</a></li>
+</ul></li>
+<li><p>Install <a href="http://www.sno.phy.queensu.ca/%7Ephil/exiftool/">ExifTool</a>.</p></li>
+<li><p>Open the <a href="http://www.addictivetips.com/windows-tips/windows-7-elevated-command-prompt-in-context-menu/">command line</a>
+and type:</p></li>
+</ol>
+
+<pre class="code text"><code class="text"> gem install halation
+</code></pre>
+
+<h2>Configuration</h2>
+
+<p>Halation stores its global configuration data in <code>.halation</code> in the system's
+user directory. This is typically <code>~/.halation</code> on Mac and *nix-based systems,
+or <code>C:\Users\.halation</code> on Windows.</p>
+
+<blockquote>
+<p>Halation uses the <a href="http://www.yaml.org/spec/1.2/spec.html#Preview">YAML syntax</a>
+for its configuration files.</p>
+</blockquote>
+
+<p>By default Halation uses a global configuration file, <code>~/.halation/config.yml</code>.
+This is where your generic settings are stored, like your name, copyright info,
+and information about your cameras.</p>
+
+<pre class="code yaml"><code class="yaml"># Example config.yml
+---
+artist: "Example User"
+copyright: "2016 Example User"
+cameras:
+ - tag: "rz67"
+ make: "Mamiya"
+ model: "Mamiya RZ67 Pro II"
+ lenses:
+ - tag: 65
+ model: "M65mm f/4L-A"
+ focal_length: 65
+ - tag: 110
+ model: "Z110mm f/2.8W"
+ focal_length: 110
+ - tag: 180
+ model: "Z180mm f/4.5W-N"
+ focal_length: 180
+ - tag: 250
+ model: "M65mm f/4L-A"
+ focal_length: 250
+</code></pre>
+
+<h2>Tags</h2>
+
+<p>Tags are user-defined values that serve as a quick and simple way to reference
+complex information.</p>
+
+<p>Why is this important? Let's say you shot a roll of ten images with several
+different lenses. It would be cumbersome to have to specify a model number
+like <code>Z110mm f/2.8W</code> (and all the other lens information) on each of the frames.
+Even more importantly, if you're processing batches of images over a long period
+of time (months, years), you're bound to make mistakes in the spelling of the
+model number. This is important because any software that catalogs images based
+on Exif data (Lightroom, Flickr) doesn't know how to deal with these
+inconsistencies. This means <code>Z110mm f/2.8W</code> and <code>Z110mm f/2.8 W</code> will be
+considered two different lenses by the software (did you see the difference?),
+even though we as humans understand they're the same thing. If you try to filter
+by lens in Lightroom, some of the images will be under one spelling and some
+will be under the other, even though they were both shot with the same
+110mm lens.</p>
+
+<p>Tags solve this problem by letting us define all of the complex,
+infrequently-changing data in one place. We can then reference that complex
+data by its <code>tag</code>. For example, if we have a 65mm lens and a 110mm lens we can
+define their information once and tag them as <code>65</code> and <code>110</code> respectively (we
+choose the tag names).</p>
+
+<pre class="code yaml"><code class="yaml">lenses:
+ - tag: 65
+ model: "M65mm f/4L-A"
+ focal_length: 65
+ - tag: 110
+ model: "Z110mm f/2.8W"
+ focal_length: 110
+</code></pre>
+
+<p>Now when we want to reference which lens was used when capturing a particular
+frame, all we have to do is specify the tag and Halation will fill in the
+correct Exif data for that lens when the image file is processed.</p>
+
+<pre class="code yaml"><code class="yaml">frames:
+ - number: 1
+ lens: 110
+ - number: 2
+ lens: 65
+ - number: 3
+ lens: 110
+</code></pre>
+
+<h2>Processing A Roll</h2>
+
+<p>Halation requires all of the image files for a roll of film to be in the same
+directory. The images should be named in ascending alphabetical order, with the
+first frame of the roll at the start of the list and the last frame at the end.
+This is typically the default when scanners save files. Halation will scan for
+tiff files (<code>.tif</code>, <code>.tiff</code>), which is the ideal format, as well as jpeg files
+(<code>.jpg</code>, <code>.jpeg</code>).</p>
+
+<p>This directory should also contain a <code>roll.yml</code> file, which specifies the data
+for each frame (image file) on the roll of film. A new <code>roll.yml</code> file can be
+generated in the current directory with the following command:</p>
+
+<pre class="code text"><code class="text"> halation --new-roll
+</code></pre>
+
+<p>The data for the roll can then be entered into the file:</p>
+
+<pre class="code yaml"><code class="yaml"># Example roll.yml
+---
+date: "2016-01-01"
+camera: "rz67"
+lens: 110
+iso: 100
+frames:
+ - number: 1
+ shutter: "1/125"
+ aperture: 8
+ - number: 2
+ shutter: "2"
+ lens: 65
+ aperture: 16
+ - number: 3
+ lens: 65
+ shutter: "0.5"
+ aperture: 16
+ - number: 4
+ lens: 65
+ shutter: "0.5"
+ aperture: 16
+ - number: 5
+ shutter: "1/250"
+ aperture: 4
+ - number: 6
+ shutter: "1/125"
+ aperture: 8
+ - number: 7
+ shutter: "1/125"
+ aperture: 8
+ - number: 8
+ shutter: "1/60"
+ aperture: 22
+ - number: 9
+ date: "2016-01-02"
+ shutter: "1/400"
+ aperture: 8
+ flash: yes
+ - number: 10
+ date: "2016-01-02"
+ shutter: "1/400"
+ aperture: 8
+ flash: yes
+</code></pre>
+
+<p>Default values can be set at the beginning of the file so that these settings
+don't have to be specified for each frame. For example, the roll of film has
+one ISO speed for all of the frames, so this can be specified at the top instead
+of for each individual frame.</p>
+
+<p>Values like the date are a little different, because maybe the whole roll was
+shot during the same day, or maybe it was shot over the course of several days.
+This is where the <code>roll.yml</code> file provides flexibility. Specifying <code>date</code> at the
+beginning of the file will make it the default date for all of the frames on the
+roll. If not all of the frames were shot on the same day, <code>date</code> can then be
+specified for each of the frames that have a different date (<code>9</code> and <code>10</code> in
+the example above). This concept works for most of the values.</p>
+
+<blockquote>
+<p>A complete list of keywords are available in the <a href="http://www.rubydoc.info/gems/halation">Halation API documentation</a>,
+as well as in the <a href="https://github.com/amclain/halation/tree/master/spec/samples">sample files</a>.</p>
+</blockquote>
+
+<p>After all of the necessary values are entered into <code>roll.yml</code>, the images can
+be processed by running the following command:</p>
+
+<pre class="code text"><code class="text"> halation
+</code></pre>
</div></div>
<div id="footer">
- Generated on Wed May 4 22:46:35 2016 by
+ Generated on Sat May 28 22:28:56 2016 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.8.7.6 (ruby-2.1.7).
</div>
</div>
\ No newline at end of file