Friday, 8 February 2019

Tool for Annotating Image Files

MetaProxy is a free little program that allows archival descriptions, search terms, provenance, and any other meta-data (i.e. data about data) to be associated with images and other file types in your genealogical data. The original program was designed to run under Windows and requires no installation, but a Mac version is also available. This article describes the Windows version.

It may be downloaded from:

This folder also includes a PDF user guide, and a description of the general principle being demonstrated can be found at:

An equivalent version for the Mac is also available via the associated Facebook group: MetaProxy Group.

So what does it do?

Unlike similar commercial programs, it does not hide your meta-data in a database, or within invisible areas of an image file, or in any other opaque form of storage; it is in plain text files that can be loaded into a simple text editor, and the content of those files is completely dictated by you.

Think of this as taking something that might normally be scribbled on the reverse of a photograph and storing it in a separate text file.

The idea of using a separate file for this purpose is not new — they're known as "buddy files", or sidecar files — but this program shows that they can be effective without having to conform to some data standard, and without having to use specialised programs to see/edit their content. The only convention is that the image and its buddy file share the same name (e.g. picture.jpg and picture.meta) and they must currently reside in the same folder as each other. Such buddy files would be copied with their neighbouring images if you ever move them, or make backups, and would be just as permanent — more permanent than using hidden meta-data inside an image because that is often wiped clean by cavalier Websites and image-editing software.

When double-clicking on a buddy file, MetaProxy finds the associated image and launches it in its default viewer, e.g. Microsoft Office Picture Manager, and then displays the content of the buddy file over the bottom third to present that extra information to you. Sound simple?

As well as providing a place for your "back of the picture" annotation, the buddy files are a good place to put search terms. We're using #hashtags in this article (e.g. for relevant surnames, places, dates, etc), but that is not an essential format. Consider, for instance, if you have a digital image of a newspaper clip, or of a handwritten will, and that you've also made a textual transcription of it. Well, if you put the transcription into the buddy file then a Windows Search will find the buddy files relevant to what you're looking for (remember that you cannot search the text inside an image file, but you can search text transcribed into a text file), and then double-clicking on any one of them would show both the original image and your transcription.

This overlay mode (the default) doesn't move or resize the image window; it simply displays the buddy-file content over the bottom third of it. There's another mode though: side-by-side, where the buddy file is displayed to the right of the image window, and together they occupy the full screen width; they both use the default height of the image window. The side-by-side option is particularly helpful with transcriptions (see Configuration).

The program doesn't care what type of image files you're using (*.jpg, *.jpeg, *.tiff, *.png, etc.) and will even work with other types of data, such as Abode Acrobat files, HTML files, or SVG family tree images. For instance, if you have an article written in a Word file called article.docx and a corresponding buddy file called article.meta, then double-clicking on the buddy file brings up both, just as with images. Not only that, if you have article.jpg and article.docx then both will be launched in their respective viewers before displaying the content of the buddy file. In other words, when you double-click on a buddy file, it will find all the files in the same folder with a matching name and display each of them.

An accidental feature of the program (one that wasn't anticipated at the start) is an ability to describe and open a collection of images, each with their own buddy file. In a demo given on Mondays with Myrt on 28 Jan 2019, an example was presented with the following files:

RisalpurCemetery.1.jpg                      First image and its buddy file
RisalpurCemetery.2.jpg                      Second image and its buddy file
RisalpurCemetery.3.jpg                      Third ...
RisalpurCemetery.4.jpg                      Fourth ...
RisalpurCemetery.meta                     Buddy file for the whole collection

That collection related to a cemetery in Pakistan, formerly British India. As described above, double-clicking on, say, RisalpurCemetery.1.meta would display that buddy file and the associated image (RisalpurCemetery.1.jpg), etc., but double-clicking on RisalpurCemetery.meta would launch the whole collection. This works because the program replaces "meta" with "*" in the initial buddy file name in order to generate a wildcard for it to find all the associated files. In this case, the generated wildcard also matches the other buddy files: the per-image ones. An accidental feature of the program (one that wasn't anticipated at the start) is an ability to describe and open a collection of images, each with their own buddy file.

The program may also be used to open your image or other data file. I'll talk more about this in a moment, but if you right-click on an image (say), select metaproxy.exe using "Open with" (but not making it the default), then it will search for an accompanying buddy file and open both, just as it did above. However, if you didn't yet have a buddy file then it will automatically create an empty one in the text editor for you.

Because these buddy files are textual, they're also searchable. This can be on specific search terms or on free text, as with transcribed data. This means that in Windows Search, you could type something like: *.meta AND #Proctor AND #1870s, and it would enumerate all the buddy files for that surname in that decade. Then double-clicking on one of these buddy files would show you both the full text from your buddy file and the accompanying image, together.

Getting it going

The program is very simple and so needs no installation. Just download the metaproxy.exe from the Dropbox folder (see above) and save it in a safe place somewhere on your hard drive.

In order to test this out, find (or create) a place where you have an image file; say image.png. You will then need to create a corresponding buddy file, image.meta, using the Notepad text editor and put some meaningful text in it. Although you can do this manually (see 'Creating Buddy Files Manually' in the PDF guide), the program will do this for you. Simply right-click your image file, select "Open with", then "Choose another app", and browse to the location of this metaproxy.exe program. You may have to follow several of these prompts, but don’t be enticed into the “app store”. Make sure the 'Always use this app to open this type of file' is unchecked before hitting 'OK'. This will create an empty buddy file for you in order to make it easier to catalogue a series of files. NB: after doing this once, the metaproxy program will be immediately available in the "Open with" list for that file type, and you won't have to search for it again.

Now right-click your completed buddy file (not the image file), select "Open with", then "Choose another app", and browse to the location of this metaproxy.exe, as you did before, but now make sure the 'Always use this app to open this type of file' is checked before hitting 'OK'. This is a one-time only task that tells Windows to always use the metaproxy.exe program whenever you double-click on a *.meta buddy file; you won't need to do this again.

From then on, when you double-click any *.meta buddy file, it will automatically open the associated files (i.e. the ones having the same names but different file types) using their registered applications (e.g. some image viewer, Microsoft Word, or whatever). It will also open the buddy file in Notepad and overlay it on the bottom third of the file's view to present any descriptive text you've created.


Although the program is self-contained and requires no mandatory configuration, provision was included for an optional INI file. This means that a text file called metaproxy.ini can be placed in the same location as metaproxy.exe in order to change the default functionality if necessary

The default settings are equivalent to the following INI-file contents:



The [metaproxy] section defines global settings. Other sections are per buddy-file type, implying that you can define several variant buddy files with different properties.

CreateType specifies the default file type to use when creating new buddy files, i.e. when opening an image with metaproxy and finding that there is no current buddy file.

SideBySide specifies that a side-by-side mode, where image and buddy file each take 50% of the screen width, is to be used for a specific buddy-file type. The default is to overlay the buddy file over the bottom third of the image. Having this option allows you to define a buddy file type that's configured to better handle transcriptions.

Editor is the name of the text editor to use for a specific buddy-file type. The editor name must be a full file specification if it is not on the normal system search path.

DelayMS is the number of milliseconds to wait between each try if the viewer for the data file (e.g. image) is taking a while to start up (default 500 milliseconds, i.e. half of a second), and DelayCount is the number of tries (default 3).

An example of an extra section for a separate *.tran buddy-file type (say, designed for transcriptions) might be as follows:


NB: whenever a file type is mentioned in this INI file, the leading period is mandatory.

NB: See also the more recent article MetaProxy (v3.0)