phloto for my photo flow | cceckman.com

Home
Résumé
Writing
Photos
Reading
Colophon

phloto for my photo flow
↑ Writing
↑ cceckman.com

2026-05-21

I’ve been taking photos lately. You can see them here.
I wasn’t satisfied with my flow for tagging, encoding, and deploying these to my site; so I wrote a houseplant program
to help. If you’re interested, you can see the code here–but, fair warning, it’s only meant to be useful to me.

A gallery in phloto, light mode

A gallery in phloto, light mode

On this page:

Digital photo development
Motivating issues

Portability
Metadata loss
Transcoding

phloto

Nondestructive editing of metadata
Peeking at containers to avoid transcodes
htmx is great

Future steps

Digital photo development
When I’m developing a photo, I run through these steps:

I take a picture.
The camera captures a RAW file with the image sensor data.
The camera embeds metadata: the camera model, lens model, timestamp, F-stop and shutter speed, etc.
This file has more data than we typically shunt around the web.
My camera has 14 bits of resolution (sensitivity) in each color channel;
most displays still only have 8 bits / channel of color resolution.

I develop the RAW file.
Using Darktable, RAWPower, or some other software,1
I process the photos. After triaging,2 I make choices like cropping, exposure, white balance…
For the photos that I’m happy with, I export a then export a developed image: a lossless 16-bit PNG.
These are very large files–in some cases, >100MB.

I convert the photo for the web.
The lossless, high-bit-depth image is good for archives; but for the web, I need something smaller,
and without a “lossless” requirement. I transcode the image into a web-safe image in the WebP format.3
I also create scaled-down versions. The “featured image” I have in the articles list
winds up being a lot smaller on your screen than the original; why bother sending the extra bits around?
The web versions also need to have filtered metadata. I’d like to be able to GPS-tag my photos
for my own usage; but I don’t want to put the coordinates of my backyard on my web site.

I write captions and alt-text for each image.
These go into the album page; but I try to embed these as additional metadata fields in the image.

Motivating issues
Before writing phloto, my process was to do (1) with the camera,
(2) with RAWPower,4 (3) with Hugo’s image filters,
and (4) in the text of the Hugo page.
This process fell down in a couple places.
Portability
When I started doing more photography, I used Darktable for steps (2) and (4).
It’s a really neat piece of software! It took me a while to understand Darktable’s flow; and even then I’m using a fraction if its power.
Even as I grew more comfortable using Darktable, I still found “open up the computer” to be a psychological barrier to doing image triage and editing.
Using a computer for this task made “deal with photos” that much more like a job or a chore.
I wound up getting a refubished iPad, with the explicit goal of using it for photo processing on the go. It lives in my camera bag rather than at my desk.
Unfortunately, an iPad can’t run Darktable.
Metadata loss
RAWPower and Nitro, in step (2), did not carry all metadata from the RAW file into the developed PNG.
Only Darktable (of the software I’ve tried) allows editing the title and description metadata fields.
The most frustrating bit: Hugo sometimes silently fails to extract Exif metadata from PNG and WebP images.
I can’t “just” pull the caption (title) and alt text (description) out of the image, even if I’ve set it.
(I’ll file a bug to Hugo for this.)
Transcoding
I was using Hugo itself for step (3), which required putting the developed files into my Git repository.
Remember, these are not yet compressed; one gallery can run to over a gigabyte of data!
Modern image compression techniques are very good at shrinking file size, but they are very CPU-intensive;5
they take time. With two galleries, the rebuild took about four minutes.
Even worse, I didn’t have Hugo caching set up properly,6 so just about every build was taking this long.
phloto
I set out with these requirements:

Web-based. The server should be accessible from my iPad, where I do the development (step 2),
and from my computer where I make the final site change.

Edit Exif title and description. I want to treat captions and alt-text as an “image” step, not as a “web” step.

Transcode with filtered Exif metadata.
I want to have my “public-safe” Exif tags set up-front, and have code that I’m in charge of do the filtering.
I want to do the transcode approximately once, rather than spending redudnant CPU cycles.

phloto does the above.
It’s a hodgepodge of untested glue between the hyper HTTP server, image and zenwebp codecs,
and my fork of the kamadak-exif library.
It’s houseplant software, with no effort to be suitable for anyone other than me.
So, y’know, don’t use it.
But it does do some neat tricks; read on for some inspiration!

This image brought to you by phloto.
Nondestructive editing of metadata
Most RAW development software uses “nondestructive editing”: they don’t modify the RAW file, ever.
Instead, they write a “sidecar” file (usually in the XMP format) that describes what modifications/interpretations to apply to the RAW data.
The software can “replay” a RAW+XMP to get the developed file (PNG).
I wanted phloto to, similarly, treat the RAW and developed files as read-only.7
But I didn’t want to deal with XMP, nor did I want to maintain a database (as Darktable does).
phloto’s hack is to read back metadata, in priority order, from each of the three files:

an existing web file, if available
the developed image (PNG)
the RAW file

The highest-priority value is kept, i.e. the first value read in the above list.
When I update metadata, phloto writes out a new web file–so the new value takes the highest priority.
Peeking at containers to avoid transcodes
In my initial implementation, phloto re-encoded every time the metadata changed.
This was Not Great, as re-transcoding results in redundant work… and takes a long time!
Luckily (?) I wound up having a mostly-complete WebP parser from an earlier stage of the project.8
Using that, phloto can open up the WebP container without actually decoding the image,
replace only the Exif data, and write the updated file back.
Now my problem is that updates are too fast–the visual feedback “I’m working on this update”
disappears before I see it!
Note that an image can get re-transcoded if the developed file (PNG) is newer than the web file (WebP).
If I want to go back and re-develop an image, I can still do that.
htmx is great
I’ve wanted to use htmx for a while, but I haven’t really had any projects that warrant it.
Everything I’ve been doing has been either exclusively server-side or exclusively client-side.
This was a nice opportunity to try it out!
htmx handles a couple things that make the interface snappy and interactive:

The first time an image is loaded, phloto doesn’t have a web-friendly version of it.9
phloto kicks off a background transcode… and via a little htmx, tells the browser
to re-load the fragment of HTML around the image.
This is an htmx load poll. While the transcode is ongoing,
the placeholder (and poll directive) remain in place. When the transcode is done,
phloto serves a new HTML fragment, without the poll–and with a texual indicator,
“webp”, that indicates the transcode is done.

The metadata update runs through a form element handled by htmx.
When the form submission completes, phloto serves back an HTML fragment
that replaces the existing form, with data read back from the file that was written,
giving a confirmation that the update is complete.

Future steps
I find myself confused as to whether the metadata is up to date, e.g. if I hit “submit”.
I probably will want to add an indicator for this.
phloto could be a little snappier at listing the contents of large directories.
Each listing of an album page has multiple “find and parse the sources for this image” calls;
caching those would probably provide a good speedup.
I might want to expose metrics, e.g. “how many transcodes are in flight”.
There is the outstanding bug where Hugo is not able to read metadata from some files;
I might need to fix this, if the issue lies with phloto or my webp editor.
But I might bypass this, either by having phloto generate markdown sources
(with alt-text and caption pre-filled), or by moving my site away from Hugo.
That said, phloto meets the requirements I was looking for.
Other than a little styling, and optionally cleaning up some of the code organization,
I don’t think there’s a much to add.

E-mail
Fediverse
RSS

I’m taking recommendations! I like the power and flexibility of Darktable,
but I want something that I can run on an iPad so I don’t have to do my editing on a full-on computer. ↩︎

I still have a lot to learn about composition and exposure. I discard a lot of captures. ↩︎

As well as JPEG as a backup, but WebP support is common in modern browsers.
I’m curious about HEIC, which in principle should be able to preserve more of the color depth.
But I need to gather more data before adding more transcoders. ↩︎

Though I’m mostly using RAWPower, I like Darktable better; it has a lot more capability, and the options/stages are clearer. However, I’ve found that having to pull out my laptop makes it less likely that I will actually develop the image. I have an iPad that I can keep in my bag and pull out when I have a free moment, and my photo development time has significantly increased. ↩︎

The Webp and AVIF formats are based on the VP8 and AV1 video codecs. VP9 was so CPU-intensive it motivated custom silicon, Google’s Video Coding Unit; that’s the same kind of computation these formats need ofr transcoding. ↩︎

I think I have now fixed this; a local rebuild takes about a second.
I’m still using Hugo for resizing operations, which involve a WebP -> WepP transcoding, and for WebP -> JPEG transcoding;
so this speed is probably only possible if those operations get memoized. ↩︎

phloto treats the “archive directory”, containing RAW and developed files, separately from the “web directory” where it writes output;
a consequence of how my directory tree is set up. Happily, this makes it easy to configure systemd to enforce this restriction!
The systemd unit I use has the archive directory under ReadOnlyPaths=, and the web directory under ReadWritePaths=;
phloto can’t clobber the RAW or developed files, because systemd won’t let it. ↩︎

Earlier in the project, I was looking for an encoder library that could do both (a) lossy WebP and (b) add Exif data.
The image crate can do (b) but not (a), lossless webp only; the libwebp crate does (a) but not (b).
One possible solution was to decode the WebP container and insert an Exif chunk.
With the help Kevan Hollbach (pairing at RC) I got a mostly-complete WebP
container parser / editor ready.
Then I found the zenwebp library, which does both, so I shelved the container parser…for a bit. ↩︎

I do not advise telling Firefox to load multiple 70MB PNGs at once. ↩︎

Prev
The Recurse Webring
Random
Next

The author describes the process of digital photo development and the challenges encountered when deploying these files for the web, which led to the motivation for creating the photo flow tool, phloto. The initial workflow involves capturing a RAW file from a camera, which contains extensive sensor data and embedded camera-specific metadata, including timestamps, focal length, and exposure settings. This raw data possesses 14 bits of resolution per color channel, which is significantly richer than the 8-bit resolution typically used by most displays. The subsequent development phase involves processing the RAW file using software like Darktable to make subjective choices regarding cropping, exposure, and white balance, resulting in high-fidelity, large image files, often exceeding 100 megabytes, typically exported as lossless 16-bit PNGs.

The transition to web optimization introduces several motivating issues: portability, metadata loss, and transcoding. Portability is complicated by the requirement to move processing capabilities between a local computer and mobile devices, leading the author to seek tools that facilitate on-the-go development, despite recognizing that dedicated software like Darktable is resource-intensive. Metadata loss arises because standard processing software often fails to correctly carry over all relevant data from the RAW file into the developed PNG, and web formats like WebP and PNG often silently fail to extract essential information like captions or alt-text, even when explicitly set. Furthermore, transcoding presents a major bottleneck; converting large, lossless files for the web requires computationally intensive processes that are slow and time-consuming, especially when dealing with large galleries, unless efficient caching strategies are implemented.

The development of phloto addressed these issues by aiming for a web-based solution that allowed editing of metadata while treating captions and alt-text as integral parts of the image data rather than separate web-layer elements. A core technical decision was to implement nondestructive editing of metadata. Instead of modifying RAW files or relying on external sidecar files like XMP (as used by other software), phloto achieves this by prioritizing metadata from three sources: an existing web file, the developed PNG, and the original RAW file. When metadata is updated, phloto writes a new web file where the most recently updated value takes the highest priority.

To handle the computationally intensive transcoding, phloto implements a method to peek into WebP containers to modify only the embedded Exif data without full image decoding, which avoids redundant work. While initial implementation involved re-encoding, the system evolved to leverage a parser to manipulate the container directly. To manage the often long processing times inherent in transcoding, the system integrated htmx to manage user interaction. This allowed phloto to initiate background transcode operations and provide dynamic feedback to the user by loading HTML fragments around the image placeholder while the transcode was running. Similarly, htmx was used for metadata updates, enabling the system to serve back updated data upon submission, confirming the completion of the update.

Future considerations for phloto involve refining the user experience by adding indicators for ongoing processes, improving the speed of directory listings through caching, and potentially addressing the outstanding issue of metadata extraction from certain web formats. The author also reflects on the broader context of image formats, noting the relevance of WebP and AVIF codecs based on video compression technology, and explores the potential of formats like HEIC, suggesting that the success of the tool ultimately lies in meeting the specific, complex requirements of the photographer's workflow.