<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ ModeShape (http://www.modeshape.org)
  ~
  ~ See the COPYRIGHT.txt file distributed with this work for information
  ~ regarding copyright ownership.  Some portions may be licensed
  ~ to Red Hat, Inc. under one or more contributor license agreements.
  ~ See the AUTHORS.txt file in the distribution for a full listing of 
  ~ individual contributors.
  ~
  ~ ModeShape is free software. Unless otherwise indicated, all code in ModeShape
  ~ is licensed to you under the terms of the GNU Lesser General Public License as
  ~ published by the Free Software Foundation; either version 2.1 of
  ~ the License, or (at your option) any later version.
  ~
  ~ ModeShape is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"	[
<!ENTITY % CustomDTD SYSTEM "../../custom.dtd">
%CustomDTD;
]>
<chapter id="image-sequencer">
  <title>Image Sequencer</title>
     <para>
			The &ImageMetadataSequencer; sequencer extracts metadata from JPEG, GIF, BMP, PCX, PNG, IFF, RAS, PBM, PGM, PPM and PSD image files.
			This sequencer extracts the file format, image resolution, number of bits per pixel and optionally number of images, comments 
			and physical resolution, and then writes this information into the repository using the following structure:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					<emphasis role="strong">image:metadata</emphasis> node of type <code>image:metadata</code>
				</para>
			</listitem>
			<listitem>
				<itemizedlist>
					<listitem>
						<para><emphasis role="strong">jcr:mixinTypes</emphasis> - "mode:derived"</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">mode:derivedAt</emphasis> - the date that at which content was sequenced to produce this record</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">mode:derivedFrom</emphasis> - the repository path to the content that was sequenced</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">jcr:mimeType</emphasis> - optional string property for the mime type of the image</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">jcr:encoding</emphasis> - optional string property for the encoding of the image</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:formatName</emphasis> - string property for the name of the format</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:width</emphasis> - optional integer property for the image's width in pixels</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:height</emphasis> - optional integer property for the image's height in pixles</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:bitsPerPixel</emphasis> - optional integer property for the number of bits per pixel</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:progressive</emphasis> - optional boolean property specifying whether the image is stored in a progressive
								(i.e., interlaced) form</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:numberOfImages</emphasis> - optional integer property for the number of images stored in the file; defaults
								to 1</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:physicalWidthDpi</emphasis> - optional integer property for the physical width of the image in dots per inch</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:physicalHeightDpi</emphasis> - optional integer property for the physical height of the image in dots per
								inch</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:physicalWidthInches</emphasis> - optional double property for the physical width of the image in inches</para>
					</listitem>
					<listitem>
						<para><emphasis role="strong">image:physicalHeightInches</emphasis> - optional double property for the physical height of the image in inches</para>
					</listitem>
				</itemizedlist>
			</listitem>
		</itemizedlist>
		<para>
			This structure could be extended in the future to add EXIF and IPTC metadata as child nodes. For example, EXIF metadata is
			structured as tags in directories, where the directories form something like namespaces, and which are used by different camera
			vendors to store custom metadata. This structure could be mapped with each directory (e.g. "EXIF" or "Nikon Makernote" or
			"IPTC") as the name of a child node, with the EXIF tags values stored as either properties or child nodes.
     </para>
		<para>
			To use this sequencer, simply include the <code>modeshape-sequencer-images</code> JAR
			in your application and configure the &JcrConfiguration; to use this sequencer using something similar to:
     </para>
   	<programlisting language="JAVA" role="JAVA"><![CDATA[
JcrConfiguration config = ...
config.sequencer("Image Sequencer")
      .usingClass("org.modeshape.sequencer.image.ImageMetadataSequencer")
      .loadedFromClasspath()
      .setDescription("Sequences image files to extract the characteristics of the image")
      .sequencingFrom("//(*.(jpg|jpeg|gif|bmp|pcx|png|iff|ras|pbm|pgm|ppm|psd)[*])/jcr:content[@jcr:data]")
      .andOutputtingTo("/images/$1");
]]></programlisting>
</chapter>
