Image Processing Tool, version 3.4

Brief Tutorial

We will demonstrate a  few of  the basic features of img.exe by way of
an example use case:

    - We've just  returned from a  photoshoot and have copied  all the
      images from our  camera to a folder called  "orig-photos" on the
      desktop.

    - We would  like for these  originals to remain untouched,  and we
      would also like  to produce a set of  smaller images for putting
      onto our website.

    - Next, we would  like to caption each of these  images with a bit
      of text that  ascribes the credit and rights to  us in the hopes
      that this will make people think twice before lifting the images
      from our site for use elsewhere without our permission.

    - Finally, we would like to add the photos from the shoot to the
      index of all the photos we've ever taken and then issue some
      queries over this index in order to find a particular image.


img.exe is a console application, so  we need a command shell in order
to interact with it.  We'll  click Start/Run..., enter "cmd", and then
enter the Desktop directory.

img.exe  works by processing  the images  that are  in one  folder and
depositing the results into another  folder.  We call these the "input
folder" and  the "output  folder."  In our  case, the input  folder is
"orig-photos."  To keep things tidy, we'll create a new folder for the
new images called "web-photos":

    C:\users\samik\Desktop>mkdir web-photos


On our  desktop are now  two folders: "orig-photos"  and "web-photos".
Our digital camera shoots at 10 megapixels,  so we need to make them a
bit smaller before putting them on the web:

    C:\...>img resize -d orig-photos -o web-photos -s "" -q 100 -m 600


This   causes  the   resize  command   to  process   every   image  in
orig-photos and put the resized version into web-photos.

The -s option followed by  the empty quotes suppresses the renaming of
the  output  files.  The  default  renaming  adds  "-resized" to  each
filename,  so IMG_1234.JPG  would  become IMG_1234-resized.jpg.   This
makes it hard to overwrite our originals, since even if we specify the
same folder for  input as for output (which we'll do  in a moment), we
still have to go out of our  way to cause the images to be updated "in
place."

The -q  option tells  the resize command  to use the  highest quality,
lowest compression  setting for JPEG encoding.  This  will create much
larger files than a lower setting (like 90, which is the default), but
we have a couple more transformations to do before we're done, so we'd
like to keep the quality high at this point.

The -m option tells the resize command to resize the longest dimension
of each image (be that the width  or height) to 600 pixels and then to
proportionately  adjust the  other dimension.   In our  photoshoot, we
took both  landscape and portrait-oriented shots  and constraining the
"maximum" dimension in  this way allows us to produce  a set of images
that are all roughly the same size even if their dimensions differ.

Of course, we also could have  used the -w or -h options to explicitly
set the width, height, or both.

So, with  the images  resized, it's  time to add  space for  a caption
beneath each image:

    C:\...>img border -d web-photos -s "" -q 100 -b 15


This  causes  the  border  command  to  process  every  image  in  the
web-photos folder.   Note that  we did not  need to specify  an output
folder because  the output  folder defaults to  be whatever  the input
folder is.   And since the input  and output folders are  the same, we
specify an empty renaming suffix to cause the images to be updated "in
place."  Also, we use the maximum JPEG quality because we've still got
one more step before our images are ready for the web.

The -b  option tells the  border command to  create a 15  pixel border
along the  bottom.  We could have used  the -t, -l, and  -r options to
create borders on the top, left, and right, respectively.  The default
color for a border is black, which is just what we want. 

Now for the captions:

    C:\...>img text -d web-photos -s "" -t "Copyright me."


This causes  the text command to  process in place every  image in the
web-photos folder and to write "Copyright me." in white, 8 point Arial
at the  bottom left, which will  fall within the black  border we just
created.  We could have used  the -l option to specify other locations
for the text like "center" or "topright", or we could have used the -x
and -y options to use absolute coordinates.

We could have  specified a specific font family,  font size, and bold,
italic, and underline with -ff, -fs, -b, -u, and -i, respectively.

Finally, we could have specified a color other than white using the -c
option.  Arguments to  the -c option can be color  names like "red" or
HTML-style values like #ff0000.  Add  an extra pair of hex digits just
after the '#'  symbol to specify transparency: #88ff0000  would be 50%
transparent red.

At  this point,  we'll copy  the contents  of "web-photos"  up to  our
website and be done with it.   Now, before we copy the original photos
to  our Pictures  folder,  we'd  like to  annotate  these images  with
additional information  that will  make them easier  to find  with the
"img query" command.  First, we'll annotate the images like so:

    C:\...>cd orig-photos
    C:\...>img annotate -l USA -l WA -l Seattle -t "Mom's birthday"


When this  command completes,  each image will  be tagged  with "Mom's
birthday" and the locations "USA", "WA", and "Seattle".  We could have
also used the -p switch to tag each image with the names of the people
in the photos.   Now, we'll copy those photos to  our Pictures folder,
and rebuild the index so that  it will contain the additional metadata
that we just added to these new photos:

    (Move or copy the images in orig-photos to Pictures)
    C:\...>cd Pictures
    C:\...>img index


When  this command  completes, the  index in  Pictures will  have been
updated with the metadata from the  images that were just added, which
means that if you were now to issue the following query:

    C:\...>img query -q "/tag/Mom's birthday"


You'll get  a list of  all the images  you just added.  You  might get
more,  of course, which  you can  address by  issuing a  more specific
query, based either on date and time, locations, or both:

    C:\...>img query -q "/location/Seattle/tag/Mom's birthday"


When you rebuilt  the index with the "img  index" command, above, only
the images  that had changed since  the last time the  index was built
were re-indexed.  This  means that you can put all  your images into a
single folder and very rapidly  re-index that folder as new images are
added, even  if that  folder contains thousands  of images  (like mine
does).

To get  the full  and complete documentation  on a given  command, say
something like:

    C:\...>img help <command>


To get an overview, say:

    C:\...>img help


Sami Khoury
Interlaced Digital, LLC
November 2014