lamka02sk/picturium
Fast and caching media server for processing images, generating thumbnails, ...
318
https://github.com/lamka02sk/picturium
Fast and caching media server for processing images, generating thumbnails and serving files on the fly
!!! Early stages of development. Some features may not work properly and can change overtime without notice. !!!
picturium relies on libvips
crate to provide libvips bindings.
This means that the maximum currently supported version of libvips is 8.15.1
.
Since building libvips while keeping system packages not broken is quite a challenge, it is recommended running picturium through Docker.
There are 3 Docker images:
This image contains ready-to-deploy picturium server with everything you are going to need.
Replace {picturium-data}
with local folder containing your .env
file data
directory containing files you want to serve.
Make sure picturium
user with UID/GID 1500 has write permissions to this folder (not necessarily your data directories).
docker run --rm -v {picturium-data}:/app -ti --init -p 20045:20045 lamka02sk/picturium:latest
Image to make development of picturium itself easier. Automatically watches for code changes and recompiles picturium.
Simply run with bash script dev.sh
in project root.
./dev.sh
Base picturium image providing libvips
and other necessary libraries for the final build.
This image is used only as base for other images.
Supports all file formats in pass-through mode, but some of them get special treatment:
AVIF_ENABLE
environment variable to false
)CACHE_CAPACITY
in GBAll files are served from the working directory. The working directory in docker images is located at /app
.
For example file located at /app/data/image.jpeg
will be available at https://.../data/image.jpeg
.
by default, picturium requires token authorization of all requests to protect against unwanted traffic
you can disable token authorization by completely removing KEY
environment variable from .env
file
tokens are SHA256 HMAC authentication codes
token is generated from file path + all URL parameters except the token
parameter, sorted alphabetically (check out RawUrlParameters::verify_token
in src/parameters/mod.rs for more)
w
(int): width of the output image in pixelsh
(int): height of the output image in pixelsar
(string): aspect ratio of the output image, when both w
and h
are set, this parameter will be ignored
auto
(default): aspect ratio will be set by w
and h
parameters, or original image dimensions if not both w
and h
are setvideo
: ratio 16/9square
: ratio 1/14/3
, 16/10
, 3/2
q
(int): quality of the output image in percent (default: dynamic quality based on the requested image dimensions)dpr
(int): device pixel ratio, multiplies w
and h
by itselfcrop
(string): crop parameters in format crop=ar:auto,w:50,h:50,g:center,x:0,y:0
; for cropping the image, at least one of w
or h
must be set
ar
: aspect ratio of the crop area
auto
(default): aspect ratio will be set by w
and h
crop parameters, or original image dimensions if not both w
and h
are setvideo
: ratio 16/9square
: ratio 1/14/3
, 16/10
, 3/2
w
: width of the crop area in pixels relative to the original image sizeh
: height of the crop area in pixels relative to the original image sizeg
: gravity / placement of the cropped area within the original image, default: center
center
: center of the original imagetop-left
|left-top
: left top corner of the original imagetop-center
|center-top
|top
: top center of the original imagetop-right
|right-top
: right top corner of the original imageleft-center
|center-left
|left
: left center of the original imageright-center
|center-right
|right
: right center of the original imagebottom-left
|left-bottom
: left bottom corner of the original imagebottom-center
|center-bottom
|bottom
: bottom center of the original imagebottom-right
|right-bottom
: right bottom corner of the original imagex
: offset on the X axis (horizontal) in pixels from the center of gravity, negative values are supportedy
: offset on the Y axis (vertical) in pixels from the center of gravity, negative values are supportedthumb
: generate thumbnail from file, or specific page of PDF documents in format thumb=p:1
p
: page of the document to generate thumbnail, default: 1
original
: default false
true
: returns original image or file, all other URL parameters are ignoredfalse
: returns processed imagerot
: rotate image, default: no
90
|left
|anticlockwise
: rotate image left by 90 degrees180
|bottom-up
|upside-down
: rotate image upside down by 180 degrees270
|right
|clockwise
: rotate image right by 90 degreesbg
: apply background color to transparent image, colors can be specified in different formats:
#ffffff
, #7a7ad3
, #000000ff
)255,124,64
)255,124,64,255
)transparent
|black
|white
)f
: specify output format, default: auto
auto
: automatically selects the best format for the requesting web browserjpg
|jpeg
: output image in JPEG formatwebp
: output image in WEBP formatavif
: output image in AVIF formatpng
: output image in PNG formatpdf
: output office document in PDF format / defaults to JPEG for images and PDF filesThe original image will be processed, rotated left by 90 degrees, resized to be 320px wide while keeping the original aspect ratio, saved with 50% quality in a format (WEBP or JPEG) supported by the requesting web browser.
https://example.com/folder/test.jpg?token=fsd5f4sd5f4&w=160&q=50&dpr=2&rot=left
picturium uses a few libraries that enforce limits on the size of images that can be processed. We tried to discover and tailor these limits to ensure stability and good (not only) developer experience.
Maximum output image resolution: 16384 x 16384 px
(reason: quantization)
Maximum output image resolution: 16383 x 16383 px
(reason: WebP format limitation)\
Maximum total output image resolution: 170 megapixels
(reason: cwebp
internal limitations)
Maximum output image resolution: 16384 x 16384 px
(reason: libvips
internal limitation)
Images included in SVG files (xlink:href
), cannot exceed memory limit of 512 MB
(https://gitlab.gnome.org/GNOME/librsvg/-/issues/1093) due to default configuration of image
crate
which cannot be increased through both librsvg
and libvips
.
According to test files found in image
crate, the memory needed to process the image (with reserve) can be calculated like this:
{image_width} * {image_height} * 5 / 1024 / 1024
We recommend including images with maximum resolution of 105 megapixels
(or for example 10000 x 10500 px
).
docker pull lamka02sk/picturium