#162 #258 Serve fullsize image on zoom (configurable)

This commit is contained in:
Alan Grainger
2026-06-30 13:01:54 +12:00
parent 494fbe36c7
commit 00da9018cf
18 changed files with 561 additions and 135 deletions
+16 -13
View File
@@ -1,8 +1,6 @@
import {
getPreviewImageSize,
getVideoContentType,
photoUrl,
requiresOriginal,
videoUrl
} from '../immich'
import { Response } from 'express-serve-static-core'
@@ -13,7 +11,8 @@ import { toString } from '../utils/text'
import { h } from 'preact'
import { renderPage } from '../view/render'
import { Gallery, GalleryItem, GalleryProps } from '../view/gallery'
import { getFilename } from './filename'
import { downloadFilename } from './filename'
import { requiresOriginal } from './sizing'
import { metadataGroupActive, pickExif } from './exif'
/**
@@ -41,6 +40,11 @@ export async function gallery (res: Response, share: SharedLink, openItem?: numb
// the operator's own config: when explicitly `false`, no EXIF / location /
// description fields are surfaced, regardless of `ipp.showMetadata.*`
const shareMetadataAllowed = share.showMetadata !== false
// Offer a zoom upgrade only when the operator opted in AND Immich would serve
// it: web `fullsize` resolves to `/original`, which Immich refuses unless the
// share's own download toggle (`share.allowDownload`) is on. Deliberately
// independent of IPP's `allowDownload` config.
const zoomUpgrade = getConfigOption('ipp.maxZoomQuality', 'preview') === 'fullsize' && share.allowDownload !== false
const descriptionInCaption = shareMetadataAllowed && !!getConfigOption('ipp.showMetadata.description.caption', false)
const descriptionInSidebar = shareMetadataAllowed && !!getConfigOption('ipp.showMetadata.description.sidebar', false)
const sidebarHasContent = shareMetadataAllowed && (descriptionInSidebar || metadataGroupActive('exif') || metadataGroupActive('location'))
@@ -63,17 +67,15 @@ export async function gallery (res: Response, share: SharedLink, openItem?: numb
})
}
// Compute the filename so the client-side `<a download="...">` attribute
// matches the bytes the server will return. Without this, a HEIC
// original served as a preview JPEG would download as "photo.heic"
// with JPEG bytes inside.
const downloadUrl = photoUrl(share.key, asset.id, ImageSize.original)
const downloadServedSize = (getConfigOption('ipp.downloadOriginalPhoto', true) || requiresOriginal(asset))
? ImageSize.original
: ImageSize.preview
const thumbnailUrl = photoUrl(share.key, asset.id, ImageSize.thumbnail)
const previewUrl = photoUrl(share.key, asset.id, getPreviewImageSize(asset))
// Always request `preview`; the resolver floors gif/video up to the
// original on its own (their preview is a static frame).
const previewUrl = photoUrl(share.key, asset.id, ImageSize.preview)
// Still images only - gif/video are already served at their highest tier.
const fullUrl = zoomUpgrade && asset.type === AssetType.image && !requiresOriginal(asset)
? photoUrl(share.key, asset.id, ImageSize.fullsize)
: undefined
// Plain text; the client uses textContent so no escaping needed here.
// Description is included if EITHER surface (caption or sidebar) wants it.
const descriptionEnabled = descriptionInCaption || descriptionInSidebar
@@ -96,11 +98,12 @@ export async function gallery (res: Response, share: SharedLink, openItem?: numb
id: asset.id,
type: asset.type,
previewUrl,
fullUrl,
thumbnailUrl,
downloadUrl,
videoData,
description: itemDescription || undefined,
downloadFilename: getFilename(asset, downloadServedSize),
downloadFilename: downloadFilename(asset),
width,
height,
thumbhash: asset.thumbhash,
+10
View File
@@ -1,6 +1,7 @@
import { Asset, ImageSize } from '../types'
import { getConfigOption } from '../config/access'
import { sanitize } from '../utils/sanitize'
import { resolveImageEndpoint } from './sizing'
/**
* Map an Immich asset MIME type to a file extension (including the dot).
@@ -89,3 +90,12 @@ export function getFilename (asset: Asset, servedSize: ImageSize = ImageSize.ori
}
}
}
/**
* Filename for a downloaded asset, whose extension matches the bytes a download
* (`/original` request) actually returns after the `maxDownloadQuality` clamp.
* Used by both the eager (gallery builder) and lazy (`/meta/`) item paths.
*/
export function downloadFilename (asset: Asset): string {
return getFilename(asset, resolveImageEndpoint(ImageSize.original, asset).servedSize)
}
+3 -10
View File
@@ -1,9 +1,8 @@
import { Asset, ImageSize, SharedLink } from '../types'
import { Asset, SharedLink } from '../types'
import { AssetMetadata } from '../shared/types'
import { getConfigOption } from '../config/access'
import { requiresOriginal } from '../immich'
import { pickExif } from './exif'
import { getFilename } from './filename'
import { downloadFilename } from './filename'
/**
* Build the on-demand metadata payload for a single asset, served by the
@@ -26,15 +25,9 @@ export function buildAssetMetadata (asset: Asset, share: SharedLink): AssetMetad
? asset.exifInfo.description
: undefined
// Match the gallery builder's download-size resolution so the filename's
// extension reflects the bytes the user will actually receive.
const downloadServedSize = (getConfigOption('ipp.downloadOriginalPhoto', true) || requiresOriginal(asset))
? ImageSize.original
: ImageSize.preview
return {
exif: shareMetadataAllowed ? pickExif(asset) : undefined,
description,
downloadFilename: getFilename(asset, downloadServedSize)
downloadFilename: downloadFilename(asset)
}
}
+146
View File
@@ -0,0 +1,146 @@
import { Asset, AssetType, ImageSize } from '../types'
import { getConfigOption } from '../config/access'
/*
Single source of truth for image-size policy: given a requested ImageSize
and an asset, decide which Immich endpoint actually serves it.
*/
export interface ImageEndpoint {
subpath: string
sizeQueryParam?: string
attachment: boolean
servedSize: ImageSize
}
/**
* Whether this asset must be served from `/original` to remain useful,
* bypassing the operator's quality ceilings.
*
* - Videos: Immich's preview/thumbnail endpoints return a poster JPEG, not the
* video, so the downgrade would replace a video file with a still image.
* - Animated images (currently just GIF): Immich's preview is a static JPEG,
* so the downgrade silently strips the animation. APNG/animated-WebP aren't
* listed because Immich doesn't expose a distinct MIME type for them - they
* share `image/png` / `image/webp` with their static counterparts.
*
* Used by both the display path (lightbox preview URL) and the download path
* (single-asset download + zip), so the lightbox shows the same bytes the
* user gets when they hit "download".
*/
export function requiresOriginal (asset: Asset): boolean {
if (asset.type === AssetType.video) {
return true
} else if (asset.originalMimeType?.startsWith('video/')) {
return true
} else if (asset.originalMimeType === 'image/gif') {
return true
}
return false
}
/*
MIME types a browser can render directly, mirroring Immich's
`isWebSupportedImage`. For these the `fullsize` tier resolves to the original
bytes (`/original`); everything else (RAW/HEIF/TIFF/...) gets Immich's
converted full-size JPEG via `?size=fullsize`.
*/
const WEB_DISPLAYABLE_MIME = new Set(['image/jpeg', 'image/png', 'image/webp'])
function isWebDisplayable (asset: Asset): boolean {
return !!asset.originalMimeType && WEB_DISPLAYABLE_MIME.has(asset.originalMimeType)
}
/*
Detail ladder for the photo tiers, ascending. THUMBNAIL is deliberately
excluded: it is the grid poster and is always served exactly as requested
(for a video/gif it is the correct still frame), so it short-circuits before
the clamp below and is never promoted or demoted.
*/
const LADDER = [ImageSize.preview, ImageSize.fullsize, ImageSize.original]
const rank = (size: ImageSize) => LADDER.indexOf(size)
const clamp = (size: ImageSize, lo: ImageSize, hi: ImageSize) =>
LADDER[Math.min(Math.max(rank(size), rank(lo)), rank(hi))]
/**
* Operator ceiling for the download tier (`ipp.maxDownloadQuality`). `original`
* is allowed here because a download needn't be browser-renderable.
*/
function maxDownloadQuality (): ImageSize {
const value = getConfigOption('ipp.maxDownloadQuality', 'original')
if (value === 'preview') return ImageSize.preview
if (value === 'fullsize') return ImageSize.fullsize
return ImageSize.original
}
/**
* Operator ceiling for the zoom tier (`ipp.maxZoomQuality`). `original` is
* deliberately not an option: a zoom upgrade must stay browser-displayable, and
* the original could be an unviewable RAW/DNG or a huge file.
*/
function maxZoomQuality (): ImageSize {
return getConfigOption('ipp.maxZoomQuality', 'preview') === 'fullsize'
? ImageSize.fullsize
: ImageSize.preview
}
/**
* Highest tier permitted for `requested`, which doubles as the intent:
* `original` (download) caps at `maxDownloadQuality`, `fullsize` (zoom) caps at
* `maxZoomQuality`. `preview` / `thumbnail` are never capped.
*/
function ceiling (requested: ImageSize): ImageSize {
if (requested === ImageSize.original) return maxDownloadQuality()
if (requested === ImageSize.fullsize) return maxZoomQuality()
return requested
}
/**
* Resolve the Immich endpoint that serves `requested` for `asset`.
*
* `servedSize` is the tier Immich will actually return after clamping, which
* may be lower than requested (e.g. an `original` downgraded to `preview` when
* `ipp.maxDownloadQuality` is `preview`). Callers use it to derive a filename
* whose extension matches the bytes (see getFilename).
*
* `attachment` reflects intent and is keyed off the REQUESTED size, not the
* served one: an `original` request is a download (gets Content-Disposition);
* preview/fullsize/thumbnail are for display. This is what lets a gif served
* from `/original` for inline display stay inline, while a gif *download* from
* the same endpoint gets the attachment header.
*/
export function resolveImageEndpoint (requested: ImageSize, asset: Asset): ImageEndpoint {
const attachment = requested === ImageSize.original
// Thumbnail is the grid poster: served as-is, never clamped (a video/gif
// thumbnail must stay a small still, not get promoted to the original file).
if (requested === ImageSize.thumbnail) {
return { subpath: '/thumbnail', attachment, servedSize: ImageSize.thumbnail }
}
// gif/video have no usable preview or fullsize (a static frame), so they are
// always served from the original file, bypassing the operator ceilings.
if (requiresOriginal(asset)) {
return endpointFor(ImageSize.original, asset, attachment)
}
const served = clamp(requested, ImageSize.preview, ceiling(requested))
return endpointFor(served, asset, attachment)
}
/**
* The one place that maps a (clamped) ImageSize onto a concrete Immich path,
* and the only place that knows `fullsize` is per-asset.
*/
function endpointFor (size: ImageSize, asset: Asset, attachment: boolean): ImageEndpoint {
switch (size) {
case ImageSize.original:
return { subpath: '/original', attachment, servedSize: ImageSize.original }
case ImageSize.fullsize:
// Web formats: fullsize is the original bytes, served from /original.
// Non-web (RAW/HEIF): Immich's converted full-size JPEG via ?size=fullsize
// (falls back to preview unless full-size generation is enabled in Immich).
return isWebDisplayable(asset)
? { subpath: '/original', attachment, servedSize: ImageSize.original }
: { subpath: '/thumbnail', sizeQueryParam: 'fullsize', attachment, servedSize: ImageSize.fullsize }
default: // preview
return { subpath: '/thumbnail', sizeQueryParam: 'preview', attachment, servedSize: ImageSize.preview }
}
}