Thumbnail Images¶

PhotoPrism uses the disintegration/imaging package to generate thumbnail images that are displayed in search results and in the full-screen viewer.

The smallest configurable size limit is 720px, which corresponds to the fit_720 thumbnail type. All sizes up to 720x720 will be generated by default and should therefore always be available.

Besides their obvious use in the frontend, the indexer uses thumbnails for color detection, face detection, and image classification, see Advanced Settings in the User Guide.

Server API¶

Like most commercial image hosting services, we have chosen to implement a cookie-free thumbnail API to minimize request latency by avoiding unnecessary network traffic:

When a browser requests static files such as images from a server over HTTPS, it is generally unnecessary to send a cookie with each request if the URLs cannot be guessed, so for most practical use cases
One possible use of cookies may be to prevent the user from intentionally or accidentally sharing confidential thumbnail URLs with others
This is possible with most image hosting services/social media sites, and could also be considered a feature if you just want to share a few thumbnails without a lot of bells and whistles
Once an image has been downloaded by someone else, blocking the original URL provides little additional security, as digital copies are just as good as the original, see info box below
Keeping that in mind, previously shared URLs can be invalidated by changing the security token in your config
This will invalidate the browser cache on all connected devices, requiring previously cached thumbnails to be downloaded again
Be aware that frequent token changes result in performance degradation and a poor user experience.

In addition to better performance, a major advantage of cookie-free thumbnails is that they can be easily integrated into a content delivery network (CDN), since there is no need to check cookies or add other complex logic on edge servers.

Web Security

Digital copies are as good as originals: Once shared and downloaded, such images should be considered "leaked" because they are cached and can be re-shared by the recipient at any time, with no sure way to get all copies back, even if the download URL becomes invalid or the service is shut down completely.

Any form of protection we could provide would essentially be "snake oil", could be circumvented, and would have a negative impact on the user experience, such as disabling the browser cache or context menu.

For the highest level of protection, it is recommended to shield your private server from the public Internet. Always use HTTPS, a VPN and/or ideally TLS client certificates and make sure that only people you trust have access to your instance.

References¶

Since most users have only one domain/host name and modern web applications can store authentication tokens in localStorage, our REST API does not require or use cookies by default.

Image Endpoint URI¶

Authenticated with SHA1 hash and additional security token:

/api/v1/t/a2195b6840f46b555719d8e22e9b080e61a7317c/10d68214/tile_500

In public mode without security token:

/api/v1/t/a2195b6840f46b555719d8e22e9b080e61a7317c/public/tile_500

The thumbnail size and aspect ratio are specified at the end, in this case tile_500, which means 500x500 pixels.

Video Endpoint URI¶

Authenticated with SHA1 hash and additional security token:

/api/v1/videos/51843134d75f4cbde534270cdd5954067f887ee6/10d68214/avc

In public mode without security token:

/api/v1/videos/51843134d75f4cbde534270cdd5954067f887ee6/public/avc

Videos can be streamed if the browser supports it. The format is specified at the end, in this case MPEG-4 AVC.

Thumbnail Types¶

The smallest configurable static and dynamic size limit is 720px, so all formats up to fit_720 should be generated by default while indexing.

Higher settings allow PhotoPrism to generate thumbnails with more detail in higher resolutions - either statically (while indexing) or dynamically (on-demand).

Name	Width	Height	Common Use
`colors`	3	3	Color Detection
`tile_50`	50	50	List Preview
`tile_100`	100	100	Maps Preview
`tile_224`	224	224	Mosaic Preview
`left_224`	224	224	TensorFlow
`right_224`	224	224	TensorFlow
`tile_500`	500	500	Cards Preview
`fit_720`	720	720	Mobile, TV
`fit_1280`	1280	1024	Mobile, HD Ready TV
`fit_1920`	1920	1200	Mobile, Full HD TV
`fit_2048`	2048	2048	Tablets, Cinema 2K
`fit_2560`	2560	1600	Quad HD, Retina Display
`fit_3840`	3840	2400	Ultra HD
`fit_4096`	4096	4096	Ultra HD, Retina 4K
`fit_7680`	7680	4320	8K Ultra HD 2, Retina 6K

See /internal/thumb/sizes.go for details.

Storage Folders¶

Generated thumbnails are cached in sub-folders of /storage/cache/thumbnails based on the SHA1 hash of the original file, for example:

/storage/cache/thumbnails/1/a/3/1a30c1f...9_100x100_center.jpg

Downscaling Filters¶

Linear¶

Bilinear interpolation takes a weighted average of the four neighborhood pixels to calculate its final interpolated value. The result is a much smoother image than the original image. When all known pixel distances are equal, then the interpolated value is simply their sum divided by four. This technique performs interpolation in both directions, horizontal and vertical. This technique gives better result than nearest neighbor interpolation and take less computation time compared to bicubic interpolation.

Cubic¶

Catmull-Rom is a local interpolating spline developed for computer graphics purposes. Its initial use was in design of curves and surfaces, and has recently been used in several applications. Catmull-Rom splines are a family of cubic interpolating splines formulated such that the tangent at each point is calculated using the previous and next point on the spline. The results are similar to ones produced by bicubic interpolation with regards to sharpness, but the Catmull-Rom reconstruction is clearly superior in smooth signal region.

Lanczos¶

The Lanczos interpolation function is a mathematical formula used to smoothly interpolate the value of a digital image between its samples. It maps each sample of the given image to a translated and scaled copy of the Lanczos kernel, which is a sinc function windowed by the central hump of a dilated sinc function. The sum of these translated and scaled kernels is then evaluated at the desired pixel. Lanczos interpolation has the best properties in terms of detail preservation and minimal generation of aliasing artifacts for geometric transformations not involving strong down sampling. However higher order Lanczos interpolation requires high computational time, which makes it unsuitable for most commercial software.

Blackman¶

Blackman is a modification of Lanczos that has better control of ringing artifacts.