light image processing server
| app | chore: vega | |
| config | chore: vega | |
| handler | chore: vega | |
| middleware | chore: vega | |
| processing | chore: vega | |
| server | chore: vega | |
| worker | chore: vega | |
| .envrc | chore: vega | |
| .gitignore | chore: vega | |
| devenv.lock | chore: vega | |
| devenv.nix | chore: vega | |
| devenv.yaml | chore: vega | |
| go.mod | chore: vega | |
| go.sum | chore: vega | |
| LICENSE | Initial commit | |
| main.go | chore: vega | |
| README.md | chore: vega | |
vega
light image processing server
operations reference
| option | aliases | arguments | argument values | default | notes | example segment |
|---|---|---|---|---|---|---|
| resize | rs | resizing_type : width : height : enlarge : extend | fit | fill | crop | stretch |
| resizing_type | rt | resizing_type | fit | fill | crop | stretch |
| size | s | width : height : enlarge : extend | int≥0 : int≥0 : 0 | 1 : 0 | 1 | 0:0:0:0 |
| width | w | width | int≥0 (0 = derive from height) | 0 | standalone width. height derived from source aspect ratio unless also set. | w:1280 |
| height | h | height | int≥0 (0 = derive from width) | 0 | standalone height. width derived from source aspect ratio unless also set. | h:720 |
| enlarge | el | enlarge | 0 | 1 | 0 | 0 = never upscale beyond source dimensions. 1 = allow upscaling. |
| extend | ex | extend | 0 | 1 | 0 | 1 = pad image with background colour to reach exact dimensions instead of cropping. |
url formats
| format | source type | pattern | example | when to use |
|---|---|---|---|---|
| plain | literal url | /{sig}/{opts}/plain/{url}@{ext} | /@signature/w:800/plain/https://i.imgur.com/abc.jpg@jpeg | easiest to read/debug. use skipclean+rawpathhandler. |
| encoded | base64url url | /{sig}/{opts}/{base64url}.{ext} | /@signature/w:800/ahr0chm6ly9plmltz3vylmnvbs9hymmuanbn.jpeg | safe against proxy/cdn path cleaning. recommended default. |
| encrypted | aes encrypted | /{sig}/{opts}/enc/{aes_url}.{ext} | /@signature/w:800/enc/u2fsdgvkx1-encrypted.jpeg | hides source url from clients. requires velo_encryption_key. |
signature = hmac-sha256(key, "/{opts}/{source_part}") encoded as base64url. set velo_skip_signature=true in dev to bypass.
combination examples
| use case | options used | option segments | plain url | builder (go) | result |
|---|---|---|---|---|---|
| thumbnail (square crop) | resize, fill mode | resize:fill:150:150 | /@signature/resize:fill:150:150/plain/https://i.imgur.com/x.jpg@jpeg | .resize("fill", 150, 150).plain(src, "jpeg") | ×ばつ150 px, center-cropped |
| responsive hero image | width only | w:1920 | /@signature/w:1920/plain/https://i.imgur.com/x.jpg@jpeg | .width(1920).plain(src, "jpeg") | 1920px wide, height from ratio |
| open graph preview | resize + fit | resize:fit:1200:630 | /@signature/resize:fit:1200:630/plain/https://i.imgur.com/x.jpg@jpeg | .resize("fit", 1200, 630).plain(src, "jpeg") | ×ばつ630, letterboxed to fit |
| avatar (allow upscale) | size + enlarge | s:200:200/el:1 | /@signature/s:200:200/el:1/plain/https://i.imgur.com/x.jpg@jpeg | .size(200,200).enlarge().plain(src, "jpeg") | ×ばつ200, upscale small sources |
| retina thumbnail | fill + exact size | resize:fill:300:300 | /@signature/resize:fill:300:300/plain/https://i.imgur.com/x.jpg@webp | .resize("fill", 300, 300).plain(src, "webp") | ×ばつ300 webp, ×ばつ for retina |
| banner with padding | size + extend | s:1200:400/ex:1 | /@signature/s:1200:400/ex:1/plain/https://i.imgur.com/x.jpg@png | .size(1200,400).extend().plain(src, "png") | ×ばつ400 padded, no crop |
| height-constrained strip | height only | h:80 | /@signature/h:80/plain/https://i.imgur.com/x.jpg@jpeg | .height(80).plain(src, "jpeg") | 80px tall, width from ratio |
| stretch to exact canvas | resize + stretch | resize:stretch:640:480 | /@signature/resize:stretch:640:480/plain/https://i.imgur.com/x.jpg@jpeg | .resize("stretch", 640, 480).plain(src, "jpeg") | ×ばつ480, distorted to fit |
| encoded source (cdn safe) | width + encoded url | w:800 | /@signature/w:800/ahr0chm6ly9plmltz3vylmnvbs94lmpwzwc.jpeg | .width(800).encoded(src, "jpeg") | base64url source, no // issues |
| type + independent size | rt + w + h | rt:fill/w:400/h:400 | /@signature/rt:fill/w:400/h:400/plain/https://i.imgur.com/x.jpg@jpeg | .resizingtype("fill").width(400).height(400).plain(src,"jpeg") | explicit per-option style |
resizing type behaviour
| type | behaviour | distorts? | crops? | best for |
|---|---|---|---|---|
| fit | scale down to fit inside ×ばつh. preserves full image. may letterbox. | no | no | thumbnails, previews, general use |
| fill | scale to cover ×ばつh, center-crop the overflow. | no | yes | avatar, hero, og images |
| crop | hard-crop to ×ばつh from center. no scaling. | no | yes | exact pixel crops |
| stretch | distort to exactly ×ばつh. ignores aspect ratio. | yes | no | fixed canvas requirements |
| fill-down | like fill but never upscale the source. | no | yes | fill without quality loss |
| force | resize to exactly ×ばつh. like stretch. | yes | no | legacy / compat alias |
| auto | alias for fit. | no | no | same as fit |