==
== PixTag Photo Description Tools
== pixtag.org
==

Digital photos are wonderful, but lack the simple feature of prints --
you can't write on the back of them.

On the surface, it seems simple enough.  When I take a picture of
Uncle Harvey, the JPEG file is one million bytes in size.  You would
think that it wouldn't be difficult to add in the twelve extra bytes
for the string "Uncle Harvey".

The problem is that everyone wants to do it differently.  In a
familiar computing industry story, each group wants to lock you into
their private database for notes, and when the technology or business
environment changes, you lose everything.  The list of contenders is
impressive: EXIF comments, RDF varieties and Dublin Core, XMP and
IPTC, NTFS file properties, the Library of Congress MODS, as well as
the internal databases maintained by each different photo organizer
(Picassa, iPhoto, Paint Shop Pro, SuperJPG, etc.)

In the past years, I have shot many photos, and since I can't jot
notes on the back, have forgotten many details about the subjects.  I
can't wait another few years for a winner to emerge before recording
this information.  I need to capture it now!

I have physical photos that are 40+ years old, and plan to keep my
digital photos for just as long.  If you believe that your current
solution will survive that long, good for you.  I don't, and this is
my open way of saving the information in a way that will survive for
many years and hopefully outlast the stupid vendor contests.

That data belongs to you!  Don't let someone else lock it up!

PIXTAG was written to scratch this particular itch.  The following are
my design goals:

   - Let me capture a basic description of photos and the events that
     they may be connected with.

   - Store the master copy of the information in a separate file, 
 	so that we never lose it if some vendor decides to strip
	things from the picture file.

   - Store the master copy in an open format so that I can write 
	tools against it or even just edit it with a text editor 
	and never be held hostage to a particular tool.

   - Copy the info into the file multiple times in all the competing
	protocols, so that it will be visible in whatever system 
	you happen to be using.

In order to make this happen, I have defined two specs that govern the
tools I write.  If others people and projects want to adopt them too,
so much the better.

The first is the pixtag file format for descriptions.  This is simple
enough to write by hand with notepad.exe or emacs (I do a lot of
this), but structured enough for tools to easily read and manage.

The second is a naming convention for files.  You can use pixtag
regardless of what you name your image files, but if you plan on
keeping your pictures for decades, you better use something better
than the IMG_1234 that comes out of your camera.  Plus, you better
plan on mixing those files with ones from other people, scans of
traditional prints, and so on.


PIXTAG DESCRIPTION FILE

There is some flexibility in how the master file is handled.  In most
cases, I expect that there will be one file with all of the pictures a
person has.  However, I can also see people partitioning the files by
year, and perhaps super-aggressive users might even loading them into
a mysql database. 

I suggest the pixtag file extension for the master files.  So for a
single file it might look like:

	loffredo.pixtag

For multiple years it might look like 

	196x_loffredo.pixtag
	197x_loffredo.pixtag
	1980_loffredo.pixtag
	1981_loffredo.pixtag

The contents of the file is simple text, so it can be edited with a
simple text editor like notepad or emacs, and processed with easy to
write tools.  A simple file is show below.

    <pixtag>

    <photo file="20030801_163001.jpg" >
      <desc>Uncle Harvey with a Monkey. The big party at Uncle
        Harvey's House</desc>
    </photo>

    </pixtag>

The entire file is enclosed by the <pixtag></pixtag> pair of tags.
Each individual photo is described by a <photo></photo> block.  Within
the opening tag, the file="filename" tells us the name of the image
file. Within the photo block, a <desc></desc> pair of tags enclose
the text describing the photo.  That's all you need for a file.

Since I am using the unique file names described below, I don't plan
on putting any directory information in the file= tag.  I plan on just
having the tools search through many directories for that unique file
name.  That way, it doesn't matter if I move pictures around, group
them into directories based on some sort of subject matter, etc.

Since we might have many photos taken during a particular event, it
would be nice to have some way to just describe that event once and
then reference it, rather than repeating the same text in every one of
the photos.  The <event></event> tag lets you do this if you want to:

    <pixtag>

    <event id="20030801_party" >
      <desc>The big party at Uncle Harvey's House</desc>
    </event>

    <photo file="20030801_163001.jpg" >
      <desc>Uncle Harvey with a Monkey</desc>
      <event ref="20030801_party" />
    </photo>

    </pixtag>

When you declare the <event>, the opening tag needs an id="eventname"
that we will use to refer to it later.  I suggest using the date, and
a short word or two separated by underscores.  Within the event block,
we use the <desc></desc> tags, the same way we do in our photo blocks,
for text describing the event.

Finally, we indicate that a photo was taken at a particular event by
putting in a reference tag of the form:

	<event ref="eventname" />

Note that the closing /> is a little different than we have seen
before, but is important.  Photos can reference as many events as you
would like.  Just add more <event ref="" /> tags to the photo block.

Technically, all of this is well-formed XML, but I don't want to make
a big deal about it, because a) the only people who care are software
developers, and b) the first thing they would want to do is make the
format more complex with various XML arcana.  The only place where you
might notice is that ampersands "&" are special in XML, so if you have
one in a description, you need to write it as "&amp;" or else tools
will complain "not well-formed (invalid token)" when they see it.

Going forward, I will define some more optional tags when it comes
time to store the EXIF camera settings from pictures, and of course, I
fully suspect that some enterprising types will add their own tags for
their personal applications.  That's fine, but for the base format, I
refer back to the design goals -- keep it simple!


IMAGE FILE NAMING CONVENTION --

For my own uses, I am adopting the following convention for file
names.  This should hold up for all of the digital photos taken by
myself and others decades into the future as well as for any print
photos from decades in the past scanned from many sources.

The key element is to name the photos by time.  For digital camera
photos, the exact time is available through the exif tag, so jhead or
some other tool can be used to extract it and rename the file.  For
scans where the exact time is not known, approximate dates, times, 
or even seasons can be used, as well as a scan sequence number.

To allow for photos from multiple people, each photo has a suffix with
the initials or other identifing tag of the source.

The general form is as follows:

   [date]_[time-or-sequence]_[personal-id].jpg

The DATE is written in year, month, day format, with some options for
just narrowing it down to months, years, or seasons as below.  If you
want to specify a range like "Sometime Sept 2-Oct 10, 1985" just do it
in your description, and make the date "1985_fal" or "198509xx"

The TIME-OR-SEQUENCE is written in hour, minute, second format with
options to narrow it as below.  If it is one of many scanned photos
from a particular event, you can use a scan sequence number instead
of the form s00001, s00002, s00003, etc.

The PERSONAL-ID should just be your initials or some other tag. For
manageability, it is best to keep it around three letters.

So here are some examples.

20030124_242902_dtl.jpg -- From digital cameras, date followed by time
			 in 24hour format, followed by three initials
			 to identify the originator.   The time includes
			 the seconds so we can have multiple photos
			 per minute.

20030124_s00001_dtl.jpg -- Scanned traditional photos, date followed by
			 a scan serial number prefixed with an "s" and
			 followed by the three initials


The jhead tool can do this renaming for you automatically based on
EXIF timestamp information in digital camera files.  The command line
invocation is as follows.  Windows uses % for shell variables so we
need to double it (%%) on Win98 to make them happy.  For some reason
WinXP command shells do not need it doubled, probably Win2k too, but 
I have not tested that.

 Windows 98  --> jhead -n%%Y%%m%%d_%%H%%M%%S_dtl  file.jpg    
 Unix, WinXP --> jhead -n%Y%m%d_%H%M%S_dtl  file.jpg    

 jhead -ta+1:00 *.jpg    --> adds one hour to the exif timestamp

In general, scanned photos should always have a date, but can then be
named based on the time if known, or a serial number if not.  When the
value is not known, "x" should be used to signal approximate values.

20030124_09xxxx_dtl.jpg -- Picture with approximate time (~9am)
200301xx_s00001_dtl.jpg -- Picture from sometime in january
197x1225_s00001_dtl.jpg -- Picture from some christmas in the 70s

The following convention can also be used to narrow things down to
a season:

2003_spr_s00001_dtl.jpg -- Scanned picture from sometime in spring

	"_spr"		sometime in spring
	"_sum"		sometime in summer
	"_fal"		sometime in fall
	"_win"		sometime in winter

2019-09-09 -- This is not close to ISO 8601, so it really does not
work well.  ISO 8601 says to drop the date for months (1972-05 for May
of 1972) but just using 00 for the date seems to be well tolerated.



RANT ON OVER-ENGINEERING

I say that Let me capture BASIC information about the photos avoid the
over-engineered "solve the general problem first" mindset that seems
to arise whenever someone starts talking about saving extra info with
files.  Jotting "Uncle Harvey with Monkey" on a photo is not an
interesting enough problem, so they inflate the scope to ANY KIND OF
TEXT IN A PHOTO, then they say why just text? so it becomes ANY KIND
OF STRUCTURED DATA IN A PHOTO, bit why just photos? so it becomes ANY
KIND OF STRUCTURED DATA IN ANY KIND OF FILE.  Now there is a problem
that you can build a career on!  Unfortunately, it will take years to
solve and debug and deploy, and in the meantime, most of america has
forgotten who that was in the photo.


The cameras makers have a little user comment field

use jhead to read/write xmp comments in the file

process it into an index file that perl can grok

use perl, superjpg and perhaps a MFC app to manage this database.




The preclick lifetime organizer is XMP based and does a pretty good
job of organizing the photos.



2017-03-06 ----------------------------------------

The IPTC Metadata Standard supplies that information, but in short:

    Headline - A brief synopsis of the caption. It's not the same as title.

    Title - A shorthand reference for the item. A human readable name
    which can be text or numeric, may be the file name, but doesn't
    have to be. It is not the same as headline.

    Caption - Is Description (as of 1.1), which is basically the
    description, including caption, of the items content.

Read through the standard, you'll probably find it interesting. Bear
in mind, it is intended for use by the International Press and it's
geared that way. By the way, from the above, the way I read the
standard is that you should be using Description (Caption) for example
you gave above. Corrected: Services like Facebook or Flicker will use
title or filename if supplied (thanks Bart).


http://www.photometadata.org/META-Resources-Field-Guide-to-Metadata#Description

Description [IPTC Core]
The Description field, often referred to as “Caption,” should report the who, what and why of what the photograph depicts. If there is a person or people in the image, this caption might include their names, and/or their roles in any action taking place. If the image depicts a location, then it should describe the location. Don’t forget to also include this same “geographical” information in the appropriate fields (location, city, state/province, country) of the IPTC Core. The amount of detail to include depends on the image and whether it is documentary or conceptual. Typically, editorial images come with complete caption text, while advertising images may not.
Note: This field is “shared” with the “Description” field in the Description panel of the Adobe Photoshop File Info dialogue.

Editorial Example:
TheShore Temple of the Seven Pagodas was built underNarsimha II of the Pallava dynasty between 7th and 8th century AD and is dedicated to Lord Shiva. It resembles the structure of the Dharmaraja rath, but its tower rises much higher (approx. five stories or ~ 60 ft. high) and its stupa spire is small and slender.

Advertising Example:
Paper tissue roll core, photographed upright.


exiftool -EXIF:ImageDescription="an EXIF CAT"  20150108_103805_dtl.jpg
exiftool -XMP:Description="an XMP CAT"   also works  20150108_103805_dtl.jpg

Time seems to have solved this issue.  XMP is now standardized as ISO
16684 (ISO 16684-1:2012 and ISO 16684-2:2014) and defines embedding in
jpg, gif, tiff, mp3, and mp4.

The dublin core XMP tags are:
Contributor 	string+ 	 
Coverage 	string 	 
Creator 	string+ 	 
Date 	date+ 	 
Description 	lang-alt 	 
Format 	string 	 
Identifier 	string 	 
Language 	string+ 	 
Publisher 	string+ 	 
Relation 	string+ 	 
Rights 	lang-alt 	 
Source 	string/ 	 
Subject 	string+ 	 
Title 	lang-alt 	 
Type 	string+

The XMP exifEX  and iptcCore, iptcExt tags are also well supported

iptcExt Event

ShownEventIdentifier / ShownEventName


Nice writeup of the tags
http://u88.n24.queensu.ca/~bogdan/articles/where_what.html



Use "jhead -autorot" to transform the image to the final orientation
and clear the flags so that it stays that way.  Avoids problems when
moving back and forth between older software that may not understand
the orientation tags.

Deleting embedded thumbnails "jhead -dt" may also help if these things
get corrupted