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. Admin interface
13. Editing an album
14. Adding photos
15. Editing a photo
16. Who can see what
17. Photo 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.

The center area Albums appear above, with the photos belonging directly to the currently selected album below. When an albumn is selected that contains no (sub)albums, the album section stays put, just the photo thumbnails are replaced. The photo viewer, info and edit panels, share this space.

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.

An album tile shows one of the album's cover photos, or, with album tiles set to info in the settings, the album's info image, or the info image from top level album when it has none.

Below the album tiles are thumbnails of the photos belonging to the selected album.

On the opening screen, this section starts with up to three larger photos side by side. They are picked at random on every visit from a published album called Favourites (or Favorites, Picks, Favorieten ) and the published albums inside it; without one, from the photos marked cover. Videos, panoramas and iiif images are never picked. The number is set under photos on the home page in the settings.

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, by default; 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.

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.

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.

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

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

The k key (kiosk mode) 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. On a touch device a two-finger tap toggles kiosk mode.

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, when 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 (only when signed in). Settings for the whole gallery, these are stored on the server:

Account. When signed out: admin login, the password field see Signing in. When signed in: logout, and change password: type the current password and the new one (at least 8 characters), then press change password. Every other device that was signed in is signed out; this one stays signed in.

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. Changing the password in the settings signs out every other device at once.

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 is editable. 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 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 uploaded 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.

Deleting a photo. Strike through every album the photo belongs to and press submit. You are asked for confirmation, then the photo is deleted for good; cancelling leaves everything as it was.

16. Who can see what

Three options determine what a visitor is shown.

published, 'On': the album is public and reachable by any visitor. 'off': it is absent from every listing and cannot be reached by guessing.

secret, 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, 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 (December 11, 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.

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, camera info, album tiles and the administrator password 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.