Photos.1st User Guide

Created from a personal need to share photos without any distractions or dependencies on private platforms.

Photos First.

Contents

1. Main screen
2. Albums
3. Viewing photos
4. Panoramas, video and iiif
5. The info panel
6. Running a slideshow
7. Full screen and kiosk mode
8. Settings
9. Keyboard shortcuts
10. Phone or tablet
11. Sending someone a link
12. Signing in
13. Editing an album
14. Adding photos
15. Editing a photo
16. Who can see what
17. Background processing

1. Main screen

Figure 1: main screen

The screen has three parts.

A top bar. At the far left, a ? opens a summary of the keys and gestures see The help panel. Next to it, a button showing a grid icon and the name of the current album; a click on it moves one level up, to the album containing this one. When a photo is open, the centre and right of the bar show the photo's title / subtitle, the date it was taken, and a counter such as 7/42. Long names are shortened with … rather than wrapping onto a second line.

The middle. The gallery itself. Albums appear as large tiles, with the photos belonging directly to the current album shown below them as thumbnails. An open photo occupies the entire middle section.

A bottom button bar.

Figure 2: button bar

2. Albums

Albums hold photos, and may contain other albums. The "Travel" album might hold "Norway 2023" and "Portugal 2024", which hold photos and potentially further albums.

Figure 3: album tiles

• Open an album: click or tap its tile, or hit the number if shown.
• Move up a level: the button at the top left showing the album name. The up arrow key does the same, as does a downward swipe on a phone or tablet.
• Shortcut numbers: the first ten albums carry a number before their name. Typing that number opens the album directly.

Below the album tiles, after a dividing line, are thumbnails of the photos belonging to the selected album, after a heading with the album's name.

Figure 4: thumbnail grid

Photos in an ordinary album appear in a different order on each visit by default. Albums marked as a trip hold photos in the order they were taken, earliest first. The order can be set per album with photo order in the album edit panel see Editing an album.

3. Viewing photos

Click or tap a thumbnail to open the photo at full size.

• Next or previous: the ‹ and › buttons, the arrow keys, or a sideways swipe.
• Return to the overview: Escape, the up arrow, or a downward swipe.

The next photo is loaded in the background while the current one is on screen, so paging through remains responsive. After the last photo the sequence returns to the first.

Large screens receive the full-size version of each photo, smaller screens a smaller one, which also loads faster on slow connections.

4. Panoramas, video and iiif

There is support for video, iiif images and 360° panorama's. These open in appropriate viewers.

Panoramas. A full-surround 360° image. Opens in a viewer that can be turned by dragging with the mouse or a finger. On a phone or tablet the handset itself can be moved to look around; permission for the motion sensor is requested the first time. Each panorama starts slightly randomised in panning speed and starting position.

Video. A video clip starts playing when it comes into view and stops when another photo is selected.

Ultra high-res. Support for very high resolution images in IIIF format. These open in a viewer that supports zooming and panning: scroll or pinch to magnify, drag to move around. The viewer is fetched the first time such an image is opened, so that first one takes a moment longer.

Figure 5: iiif image

On a phone, the ‹ and › buttons remain visible for panoramas and deep-zoom images, since a swipe there turns or pans the view rather than advancing to the next photo.

5. The info panel

The ⓘ button, or the i key, shows the details behind the current album or photo.

For an album: the album's info picture, the number of photos, the location, the description, and the range of dates over which the photos were taken. For a trip, the dates of the trip.

For a photo: title, subtitle, location, date taken and description, alongside the camera details body, lens, focal length, aperture, shutter speed and ISO. The camera details can be hidden for the whole gallery with show camera info in the settings.

Where the photo carries coordinates, a show on map link opens a map in a new window at the position of the photo.

When signed in, the photo panel also shows the photo's number, whether it has an HDR gain map, and whether it is marked as a candidate cover image.

Pressing ⓘ again closes the panel.

5.1 The help panel

The ? at the top left of the screen, in the button bar on a phone or tablet, or the ? key summarises everything the gallery responds to: the keys, the gestures, and the editing shortcuts. It appears below the top bar and closes again on any key, tap or click.

Figure 6: The help panel.

6. Running a slideshow

The ▶ button, or the space bar, starts a slideshow. A thin bar along the bottom of the screen indicates the time remaining on the current photo.

• To stop: ❚❚, or the space bar again.
• Manual navigation remains available while a slideshow runs; the timer restarts on the photo selected.
• For the interval, see Settings.

7. Full screen and kiosk mode

Full screen the ⤢ button or the f key removes the browser interface, leaving only the photos. The same button, or Escape, restores it.

The kiosk view the k key hides the top bar and the button bar, leaving nothing around the photo. The arrow keys and the slideshow continue to work. Pressing k again restores the bars.

Used together, the two produce a clean display suitable for a large screen, a presentation or an exhibition.

8. Settings

The ⚙ button, or the s key, opens the settings window. It is divided into sections; site appears only when signed in.

Figure 7: settings window, signed in.

Viewing slide show delay. A list with 4, 8 and 15 seconds, half a minute, etc. A new choice applies at once, also to a slideshow that is already running. It is stored on the device and applies to subsequent visits.

Site section (signed in only). Settings for the whole gallery, these are stored on the server:

save stores changes, a reason they could not be saved appears beside the button. Stripping, credits and sizes apply to photos uploaded from then on; photos already in the gallery keep what they were made with.

Account. Signed out: admin login, the password field see Signing in. Signed in: logout.

close dismisses the window, as does Escape.

9. Keyboard shortcuts

The gallery can be operated entirely from the keyboard. These keys are active except while typing into a field.

10. Phone or tablet

• Swipe sideways for the previous or next photo.
• Swipe down to move up to the album above.
• Tap a tile or thumbnail to open it.
• The button bar is hidden in portrait orientation to leave more room for the photo. A tap along the bottom edge restores it; it withdraws again after a few seconds without input. It carries the ? here, and the ✏ when signed in.
• Two-finger tap turns the bare view on or off, as the k key does.
• Editing on a tablet is reached with the ✏ in the button bar, there being no keyboard for the e key. Editing on a phone is not advised.
• Panoramas respond to movement of the handset as well as to dragging. The motion sensor requires permission on first use; without it, dragging still works.

11. Sending someone a link

The address in the browser's address bar follows the current position in the gallery. Copying and sending it brings the recipient to the same album.

To share one particular photo, open it and press ⌘C (Ctrl-C on Windows and Linux). This copies an address of the form …/collections/12/photo/345, which opens the album with that photo on screen. When the album was opened with a secret link, the secret is included, so the recipient can see it too.

Instructions may be appended to the address, after a question mark:

Instructions combine with & between them, for example ?kiosk&slideshow=15. A single address of this form is sufficient to drive an unattended display in a waiting room or at an exhibition.

12. Admin Interface

The remaining sections concern the upkeep of the gallery: creating albums, adding photos and maintaining their details. All of it requires signing in.

Figure 8: signing in.

1. Open settings with the ⚙ button or the s key.
2. Enter the password in the admin login field.
3. Press login, or Enter.

The page reloads, and albums and photos hidden from ordinary visitors become visible. The settings window then shows the site section and a logout button. A wrong password simply leaves you signed out.

The sign-in lasts a week on that device; after that, sign in again.

The signed-in state persists on the device until logout, so log out on shared or public computers.

13. Editing an album

Open the album and press e, or use the ✏ button in the button bar. The edit panel opens below the top bar.

Figure 9: album edit panel.

• trip for a journey or an event with a beginning and an end. Photos are then held in the order they were taken rather than shuffled, and the date field appears. Enter two months separated by a slash, for example Jun 2024 / Jul 2024. A single month is sufficient where the range is one month: Sep 2023 is equivalent to Sep 2023 / Sep 2023.
• published on makes the album public to any visitor. Off removes it from view entirely: it appears in no listing. Signed-in administrators still see it, as do visitors holding the word set in secret.

Formatting the description. The description field accepts markdown formatting

Markdown text is replaced by the formatted text it describes; plain text is equally acceptable.

The buttons at the foot of the panel:

• cancel closes the panel, discarding changes.
• submit saves and closes the panel.
• delete album removes the album, after a confirmation. Photos that belong to no other album are deleted with it, image files included; photos that also appear in other albums stay. An album that still contains other albums cannot be deleted: move or delete those first. This cannot be undone.
• new album present only in the edit panel of the opening screen. It creates an empty album; give it a name, set belongs to, and press submit.

The info picture is replaced by dragging an image onto the Album Info Image box JPG, PNG or AVIF. A preview appears immediately; submit commits it.

14. Adding photos

Open the album's edit panel with e, or the ✏ button, and use the Upload Zone box.

Figure 10: The upload zone.

Either drag the photos from the desktop onto the box, which highlights as they pass over it, or click the box and select them several at once if required in the window that opens.

A button in the corner of the box then reads upload 12 images, or the appropriate count. Pressing it sends the photos; pressing submit sends them together with the rest of the changes.

The photos are sent one at a time; the button counts down (uploading… 7 to go). When the last one is done, the album reloads by itself and the new photos appear. Photos that could not be processed are listed together in one message at the end, with the reason for each.

Accepted formats: JPG and AVIF, with or without gain map. Other files are refused.

Each photo is prepared in three sizes, and its camera details and coordinates, where present, are read from the file. Section 17 describes this processing in detail.

15. Editing a photo

Open the photo and press e, or use the ✏ button in the button bar.

Figure 11: photo edit panel.

Left-hand side:

Right-hand side:

• collections the albums this photo belongs to; a photo may appear in several at once.
  • add to… lists the albums the photo can be added to (trips and the opening screen excepted); selecting one adds the photo.
  • The cross before an album name removes the photo from that album. The name is struck through and disappears on saving.
• camera details read from the photo file: camera, lens, focal length, aperture, shutter speed, ISO and date taken. These are not editable.

At the foot of the panel, cancel discards changes and submit saves them.

Deleting a photo. Strike through every album the photo belongs to and press submit. The gallery asks for confirmation, then deletes the photo for good, files included, and returns to the album. Cancelling leaves everything as it was.

16. Who can see what

Three options determine what a visitor is shown.

published, on an album. On, the album is public and reachable by any visitor. Off, it is absent from every listing and cannot be reached by guessing.

secret, on an album. This shares an unpublished album with a defined group. Set a secret word wedding2024, for instance and distribute the album's address with ?secret=wedding2024 appended. That link grants access while published remains off; without it, nothing is visible. Also gives access to private photos within the album.

private, on a photo. For an individual photo that should not be shown in a public album. It is withheld from ordinary visitors and never shown to them. It remains visible while signed in and, inside the album, for people holding the album secret.

17. Photo processing

An uploaded photo passes through several steps before it appears in the gallery.

The following exif data is read out and applied:

The semicolon convention allows both lines to be set from one field: a title of Great Tit; Parus major yields "Great Tit" as the title and "Parus major" as the subtitle. Everything imported this way can be amended afterwards in the photo's edit panel.

When a file carries no date, the photo is assigned one in the distant past the year 1413 which makes photos lacking a date straightforward to identify.

Each photo is prepared in three versions: large, medium and small (thumb), all in the AVIF format irrespective of what was uploaded. The gallery selects between them automatically small for thumbnails, medium for phones and small windows, large for full-size screens. Their sizes are set in the settings window. A photo smaller than a requested size is kept at its own size rather than enlarged.

Photos that carry an HDR gain map keep it in all three versions, and are shown in high dynamic range on screens and in browsers that support it.

• The photo's details (title, camera and exposure, date, coordinates) are read from the uploaded file first.
• Next, where artist into exif and copyright into exif are filled in in the settings, they are written into the file, replacing its own artist and copyright.
• Then the three versions are made. They keep the camera and exposure details, the date, and the artist and copyright of the file, unless strip all metadata from stored files is on: then only the artist and copyright are kept (along with the colour profile and any HDR gain map).
• The uploaded file is discarded once processing is complete. The gallery is not an archive; originals must be retained separately.

Certain files are stored exactly as supplied rather than resized; they are only used as thumbnails.

Panoramas, video clips and iiif images are uploaded separately (for now). What is uploaded through the gallery is a stand-in image a still from the video, an overview of the panorama, a fixed view of the iiif; the literal filename of this image is what determines the type on the server:

Afterwards, open the photo, press e, and enter the name of the associated panorama directory, video file or iiif folder in the second field labelled pano dir, video file or subtitle accordingly.

The Album Info Image is handled separately: it is cropped to a square from the centre, and all information in the file is cleared except the photographer's name and the copyright notice it carried.

Resizing and reading take a moment per photo; can be an appreciable amount for fifty. Photos are processed one after another as they arrive; the upload button shows how many are still to go, and the album refreshes when all are done.

Configurable parameters

Image sizes, the artist and copyright credit, stripping and camera info are changed in the settings window while signed in. The server's settings file only supplies their starting values, when the gallery is first started. The rest is held in that settings file and adjusted by whoever administers the server.