Working with Metadata
The first thing you need to know about metadata (data about data) in Pixplot is: it's optional. You can create a basic visualization of your pictures with nothing more than a folder full of images called, let's say, "flowers":
pixplot --images "flowers/*.jpg"
Nearly everything about Pixplot will work with just this one command-line argument: zooming and scrolling, seeing one image close-up, and changing layouts. So why would you want to add metadata to the mix? Let's examine a few use cases.
First, let's set up the absolute minimum of what we need to use metadata: a CSV (comma-separated values) text file with one column, one header, and three data rows:
| filename |
|---|
| flower1.jpg |
| flower2.jpg |
| flower3.jpg |
We'll call this file flower-metadata.csv and save it in the same place where our flowers folder is.
We can re-run Pixplot and tell it to use this metadata, even though it doesn't do much yet:
pixplot --images "flowers/*.jpg" --metadata "flower-metadata.csv"
There's not much point in looking at the result -- but you will get some warning messages if you have more lines in your metadata file than you have images, or vice versa. These warnings won't stop your visualization from being built, but they are good to watch for as you debut your metadata file.
Let's say you've downloaded your images from a museum website, and you'd like to let uses see their original context. You can do this by adding in a permalink column to your metadata file:
| filename | permalink |
|---|---|
| flower1.jpg | http://example.com/flower1.html |
| flower2.jpg | http://example.com/flower2.html |
| flower3.jpg | http://example.com/flower3.html |
Each of these links will then be attached to its respective image when you click on a picture and invoke the "lightbox mode". The link icon is the eye at the right of this image:
Sometimes file names don't make it clear what an image is. We can add actual descriptions to the pictures by using a description column:
| filename | description |
|---|---|
| flower1.jpg | Red Flower |
| flower2.jpg | "Blue Flower, collected in Greece." |
| flower3.jpg | Orange Flower |
Because we're using the CSV format for our metadata, which uses commas to separate fields, it's important to enclose any descriptions that contain a comma in double quotes. The second line in the file above does this.
If your collection of images spans a long time period, it can be interesting to allow users to see how different date thresholds affect the visualization. We can enable this by adding a year column:
| filename | year |
|---|---|
| flower1.jpg | 1997 |
| flower2.jpg | 1960 |
| flower3.jpg | 2002 |
Currently, Pixplot expects years to be a four-digit integer between 1 and the current year. This means that dates such as 1997-03-12 should be shortened to 1997.
It's very common that your dataset might contain values such as "1930s" or "around 1930" instead of a precise year. These values won't stop your visualization from being built, but they will generate warning messages. You may wish to use a tool such as Open Refine to see how many of your years are "well formed", which is to say between 1 and 2021.
You don't have to add years for every row, but if you find you have a dataset with very spotty time coverage, you may wish to reconsider using this column. We've found it works best when your images is 80-90% well-dated.