{"id":13697740,"url":"https://github.com/cubicdaiya/ngx_small_light","last_synced_at":"2025-04-04T15:09:15.761Z","repository":{"id":3579363,"uuid":"4642174","full_name":"cubicdaiya/ngx_small_light","owner":"cubicdaiya","description":"Dynamic Image Transformation Module For nginx.","archived":false,"fork":false,"pushed_at":"2024-07-16T13:38:31.000Z","size":365,"stargazers_count":475,"open_issues_count":19,"forks_count":80,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-03-28T14:06:27.075Z","etag":null,"topics":["gd","imagemagick","imlib2","nginx"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cubicdaiya.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-06-12T19:51:21.000Z","updated_at":"2025-02-15T12:18:32.000Z","dependencies_parsed_at":"2024-10-27T10:57:01.771Z","dependency_job_id":"008b9491-d97f-4fc7-b61b-0b3296e5180e","html_url":"https://github.com/cubicdaiya/ngx_small_light","commit_stats":{"total_commits":297,"total_committers":8,"mean_commits":37.125,"dds":0.101010101010101,"last_synced_commit":"a13a03e2b771c420c5d71000cc551aae812cd27e"},"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cubicdaiya%2Fngx_small_light","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cubicdaiya%2Fngx_small_light/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cubicdaiya%2Fngx_small_light/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cubicdaiya%2Fngx_small_light/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cubicdaiya","download_url":"https://codeload.github.com/cubicdaiya/ngx_small_light/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198461,"owners_count":20900080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gd","imagemagick","imlib2","nginx"],"created_at":"2024-08-02T18:01:02.234Z","updated_at":"2025-04-04T15:09:15.743Z","avatar_url":"https://github.com/cubicdaiya.png","language":"C","funding_links":[],"categories":["Third Modules","Third Party Modules","C"],"sub_categories":["C Modules"],"readme":"# ngx_small_light\n\nA dynamic image transformation module for [nginx](http://nginx.org/).\n\n# Table of contents\n\n* [Features](#features)\n* [Supported Formats](#supported-formats)\n* [Dependencies](#dependencies)\n* [Installation](#installation)\n * [Dynamic module](#dynamic-module)\n* [Getting started](#getting-started)\n* [Configuration example](#configuration-example)\n* [Directives](#directives)\n * [small_light](#small_light)\n * [small_light_getparam_mode](#small_light_getparam_mode)\n * [small_light_material_dir](#small_light_material_dir)\n * [small_light_pattern_define](#small_light_pattern_define)\n * [small_light_imlib2_temp_dir](#small_light_imlib2_temp_dir)\n * [small_light_buffer](#small_light_buffer)\n* [Parameters for small_light function](#parameters-for-small_light-function)\n* [Named Pattern](#named-pattern)\n* [Using GET parameters](#using-get-parameters)\n* [Enabling WebP transformation](#enabling-webp-transformation)\n* [Optimizing Tips](#optimizing-tips)\n * [JPEG hinting](#jpeg-hinting)\n * [Limit thread-number with OpenMP](#limit-thread-number-with-openmp)\n* [Limitations](#limitations)\n * [Not supported features with Imlib2](#not-supported-features-with-imlib2)\n * [Not supported features with GD](#not-supported-features-with-gd)\n * [Not supported animated GIF](#not-supported-animated-gif)\n* [Running Tests](#running-tests)\n* [License](#license)\n\n## Features\n\nSupports the various image-processings below.\n\n * Resize\n * Rotate\n * Sharpen\n * Unsharpen\n * Blur\n * Border\n * Canvas\n * Crop\n * Composition\n * JPEG Hinting(except GD)\n * Format convert(e.g. PNG -\u003e JPEG)\n * Color-space convert(e.g. CMYK -\u003e sRGB)\n\n`ngx_small_light` is developed for using as the same way as [mod_small_light](https://github.com/yamac/smalllight) as possible in nginx.\n\n## Supported Formats\n\nSupports the formats below.\n\n * JPEG\n * GIF(except Imlib2)\n * PNG\n * WebP(except Imlib2)\n\n## Dependencies\n\n - [PCRE](http://www.pcre.org/) (required)\n - [ImageMagick](http://www.imagemagick.org/script/index.php) (required)\n - [Imlib2](http://docs.enlightenment.org/api/imlib2/html/) (optional)\n - [GD](http://libgd.bitbucket.org/) (optional)\n\n## Installation\n\n```sh\ncd ${ngx_small_light_src_dir}\n./setup\ncd {$nginx_src_dir}\n./configure --add-module=${ngx_small_light_src_dir}\nmake\nmake install\n```\n\nIf you want to enable the libraries except ImageMagick in `ngx_small_light`, add the options below when executing `setup`. (ImageMagick is always enabled)\n\n```sh\n./setup                         # enable ImageMagick\n./setup --with-imlib2           # enable ImageMagick and Imlib2\n./setup --with-gd               # enable ImageMagick and GD\n./setup --with-imlib2 --with-gd # enable ImageMagick and Imlib2 and GD\n```\n\n### Dynamic module\n\nYou can also compile `ngx_small_light` as the dynamic module with `--add-dynamic-module` in nginx-1.9.11 and ngx_small_light-0.6.15 or later.\n\n```sh\ncd ${ngx_small_light_src_dir}\n./setup\ncd {$nginx_src_dir}\n./configure \\\n--modules-path=/usr/local/nginx/modules \\\n--add-dynamic-module=${ngx_small_light_src_dir}\nmake\nmake install\n```\n\nAdd the configuration below for loading module dynamically.\n\n```nginx\nload_module /usr/local/nginx/modules/ngx_http_small_light_module.so;\n```\n\n## Getting started\n\nAdd the configuration below to some server context in nginx.conf and start nginx.\n\n```nginx\nsmall_light on;\nlocation ~ small_light[^/]*/(.+)$ {\n    set $file $1;\n    rewrite ^ /$file;\n}\n```\n\nIf you can get the original image of image.jpg from the URL below,\n\n```\nhttp://$host:$port/img/image.jpg\n```\n\nYou will be able to get the converted image of image.jpg from the URL below.\n\n```\nhttp://$host:$port/small_light(dw=300,dh=300)/img/image.jpg\n```\n\nThe part of `small_light(...)` is called **small_light function**.\n\n## Configuration example\n\nThere is some configuration example below.\n\n```nginx\nserver {\n    listen 8000;\n    server_name localhost;\n\n    small_light on;\n    small_light_pattern_define msize dw=500,dh=500,da=l,q=95,e=imagemagick,jpeghint=y;\n    small_light_pattern_define ssize dw=120,dh=120,da=l,q=95,e=imlib2,jpeghint=y;\n\n    # http://localhost:8000/small_light(p=msize)/img/filename.jpg -\u003e generate msize image\n    # http://localhost:8000/small_light(p=ssize)/img/filename.jpg -\u003e generate ssize image\n    # http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -\u003e generate gif image which quality is 100\n    location ~ small_light[^/]*/(.+)$ {\n        set $file $1;\n        rewrite ^ /$file;\n    }\n} \n```\n\n## Directives\n\n### small_light\n\n|Syntax     |*small_light on \u0026#124; off*|\n|-----------|---------------------------|\n|**Default**|off                        |\n|**Context**|server, location           |\n\nThis directive sets whether image-processing with `ngx_small_light` is enabled in a server context.\n\n### small_light_getparam_mode\n\n|Syntax     |*small_light_getparam_mode on \u0026#124; off*|\n|-----------|-----------------------------------------|\n|**Default**|off                                      |\n|**Context**|server, location                         |\n\nThis directive sets whether converting-image is enabled by GET parameters \ninstead of **small_light function** (e.g. `/small_light(dw=200,dh=200)`).\nAt the expense of it, a **small_light function** is disabled.\nBut you need to set both `small_light` and `small_light_getparam_mode` **on** to enable the feature of this directive.\n\n### small_light_material_dir\n\n|Syntax     |*small_light_material_dir path*|\n|-----------|---------------------------------------------|\n|**Default**|                                             |\n|**Context**|server                                       |\n\nThis directive assigns the directory for embedded icon images.\n\n### small_light_pattern_define\n\n|Syntax     |*small_light_pattern_define pattern_name parameters*|\n|-----------|----------------------------------------------------|\n|**Default**|                                                    |\n|**Context**|server                                              |\n\nThis directive names comma-delimited parameters.\n\n### small_light_radius_max\n\n|Syntax     |*small_light_radius_max number*|\n|-----------|-------------------------------|\n|**Default**|10                             |\n|**Context**|server,location                |\n\nThis directive sets maximum radius value of geometry for `sharpen` and `unsharp` and `blur`.\n\n### small_light_sigma_max\n\n|Syntax     |*small_light_sigma_max number*|\n|-----------|-------------------------------|\n|**Default**|10                             |\n|**Context**|server,location                |\n\nThis directive sets maximum sigma value of geometry for `sharpen` and `unsharp` and `blur`.\n\n### small_light_imlib2_temp_dir\n\n|Syntax     |*small_light_imlib2_temp_dir path* [*level1* [*level2* [*level 3* ]]]|\n|-----------|---------------------------------------------------------------------|\n|**Default**|small_light_imlib2_temp 1 2                                          |\n|**Context**|server                                                               |\n\nThis directive assigns the directory for temporary file for Imlib2 processing.\nThis directive is available when Imlib2 is enabled.\n\n### small_light_buffer\n\n|Syntax     |*small_ligh_buffer size*|\n|-----------|------------------------|\n|**Default**|1m                      |\n|**Context**|server                  |\n\nThis directive assigns the maximum size of the buffer used for reading images\nwhen Content-Length is not set in response headers.\n\n## Parameters for small_light function\n\n|Parameter  |Type  |Default    |Description                                     |ImageMagick|Imlib2|GD |\n|-----------|------|-----------|------------------------------------------------|-----------|------|---|\n|p          |string|           |named pattern of comma-delimited parameters     |        :o:|   :o:|:o:|\n|e          |string|imagemagick|engine name (imagemagick, imlib2, gd)           |           |      |   |\n|q          |number|           |quality                                         |        :o:|   :o:|:o:|\n|of         |string|           |output format (jpg, gif, png, webp)             |        :o:|   :o:|:o:|\n|jpeghint   |char  |n          |enable jpeg hinting (y, n)                      |        :o:|   :o:|:x:|\n|dw         |coord |sw         |destination width                               |        :o:|   :o:|:o:|\n|dh         |coord |sh         |destination height                              |        :o:|   :o:|:o:|\n|dx         |coord |sx         |destination x coordinate                        |        :o:|   :o:|:o:|\n|dy         |coord |sy         |destination y coordinate                        |        :o:|   :o:|:o:|\n|da         |char  |l          |destination aspect ratio contol (l, s, n)       |        :o:|   :o:|:o:|\n|ds         |char  |n          |destination scaling control (s, n)              |        :o:|   :o:|:o:|\n|cw         |number|           |canvas width                                    |        :o:|   :o:|:o:|\n|ch         |number|           |canvas height                                   |        :o:|   :o:|:o:|\n|cc         |color |000000     |canvas color                                    |        :o:|   :o:|:o:|\n|bw         |number|           |border width                                    |        :o:|   :o:|:o:|\n|bh         |number|           |border height                                   |        :o:|   :o:|:o:|\n|bc         |color |000000     |border color                                    |        :o:|   :o:|:o:|\n|sw         |coord |           |source witdh                                    |        :o:|   :o:|:o:|\n|sh         |coord |           |source height                                   |        :o:|   :o:|:o:|\n|sx         |coord |           |source x coordinate                             |        :o:|   :o:|:o:|\n|sy         |coord |           |source y coordinate                             |        :o:|   :o:|:o:|\n|pt         |char  |n          |pass through control (y, n)                     |        :o:|   :o:|:o:|\n|sharpen    |string|           |radius,sigma (e.g. 10x5)                        |        :o:|   :o:|:o:|\n|unsharp    |string|           |radius,sigma,amount,threshold (e.g 2x5+0.5+0)   |        :o:|   :x:|:x:|\n|blur       |string|           |radius,sigma (e.g. 5x10)                        |        :o:|   :o:|:x:|\n|embedicon  |string|           |embedded icon file in `small_light_material_dir`|        :o:|   :x:|:x:|\n|ix         |number|0          |embedded icon x coordinate                      |        :o:|   :x:|:x:|\n|iy         |number|0          |embedded icon y coordinate                      |        :o:|   :x:|:x:|\n|angle      |number|0          |angle of rotation (90, 180, 270)                |        :o:|   :o:|:o:|\n|progressive|char  |n          |make JPEG progressive (y, n)                    |        :o:|   :x:|:x:|\n|cmyk2rgb   |char  |n          |convert colorspace from CMYK to sRGB (y, n)     |        :o:|   :x:|:x:|\n|rmprof     |char  |n          |remove profile (y, n)                           |        :o:|   :x:|:x:|\n|autoorient |char  |n          |enable adjust image orientation automatically (y, n)  |  :o:|   :x:|:x:|\n\nThe values of `da` are `l` and `s` and `n`. These present the meanings below.\n\n * `l`: long-edge based\n * `s`: short-edge based\n * `n`: nope\n\nThere are any limitations below.\n\n * `of=gif` and `of=webp` are not supported when `e=imlib2`.\n * `autoorient` is available ImageMagick-6.9.0 or later.\n * The value of `radius,sigma` for `sharpen` and `unsharp` and `blur` is limited by `small_light_radius_max` and `small_light_sigma_max`.\n\nThere are the types of each parameter below.\n\n|Type  |Description                                      |\n|------|-------------------------------------------------|\n|coord |coordicante or pixel. percent when appending 'p' |\n|char  |character                                        |\n|number|integer number                                   |\n|color |rrggbb or rrggbbaa                               |\n|string|string                                           |\n\n## Named Pattern\n\n`ngx_small_light` supports to name comma-delimited parameters with the `small_light_define_patern`.\n\n```nginx\nsmall_light_pattern_define small dw=120,dh=120,q=80,e=imagemagick,jpeghint=y;\n```\n\nIf the line above is added to some server context in nginx.conf, the two URLs below return same response.\n\n * `http://$host:$port/small_light(p=small)/img/image.jpg`\n * `http://$host:$port/small_light(dw=120,dh=120,q=80,e=imagemagick,jpeghint=y)/img/image.jpg`\n\n## Using GET parameters\n\n`ngx_small_light` supports to convert image not only by **small_light function** but by GET paramenters in `v0.5.0` or later.\nYou need to set both `small_light` and `small_light_getparam_mode` **on** to enable this feature.\nAt the expense of enabling this feature, **small_light function** (e.g. `/small_light(dw=300,dh=300)/img.jpg` is disabled.\n\n```nginx\nsmall_light on;\nsmall_light_getparam_mode on;\n```\n\nIn the configuration above, the url below does not return converted image.\n\n```\nhttp://localhost:8000/small_light(dw=200,dh=200)/img/image.jpg\n```\n\nInstead the url below returns converted image expected by right.\n\n```\nhttp://localhost:8000/img/image.jpg?dw=200\u0026dh=200\n```\n\n## Enabling WebP Transformation\n\n`ngx_small_light` supports WebP transformation with ImageMagick and GD.\nGiven `of=webp` to **small_light function**, `ngx_small_light` transforms image format into WebP.\nBut ImageMagick requires libwebp and GD requires libvpx.\nYou need to embed these libraries in building ImageMagick and GD for enabling WebP transformation.\n\nIf WebP transformation is not available, `nginx` outputs the line like below in error.log in processing image with `of=webp`.\n\n```\nWebP is not supported\n```\n\nIf WebP transformation with ImageMagick is available, the output of `convert -list format` includes the line like below.\n\n```\n$ convert -list format | grep -i webp\n     WEBP* WEBP      rw-   WebP Image Format (libwebp 0.5.0[0208])\n```\n\nIf WebP transformation with GD is available, the output of `gdlib-config --libs` includes `-lvpx`.\n\nIn general, the packages of ImageMagick and GD provided from the linux distributions\nsuch as Ubuntu and CentOS does not embed the library for WebP transformation by default.\nIn such cases, you need to build ImageMagick or GD yourself.\n\n## Optimizing Tips\n\nThere are some optimizing tips for `ngx_small_light`.\n\n### JPEG hinting\n\nWhen the output format is JPEG and image-converting engine is ImageMagick or Imlib2,\nyou may give `jpeghint=y`. The speed of processing images is improved dramatically.\n\n### Limit thread-number with OpenMP\n\nWhen image-converting engine is ImageMagick and the version of `ngx_small_light` is lower than `v0.6.14`, \ngiving 1 to `OMP_NUM_THREADS` or `MAGICK_THREAD_LIMIT` in `nginx.conf` is recommended strongly.\nBecause OpenMP is enabled in ImageMagick by default and ImageMagick enabled OpenMP is very slow on multi-process environment.\n\n```nginx\nenv OMP_NUM_THREADS=1; # or env MAGICK_THREAD_LIMIT=1;\n```\n\nOr you can avoid this problem by building ImageMagick with `--disable-openmp`.\n\nIn `v0.6.14` or later, they are no longer required. Because `ngx_small_light` always sets the thread-number with OpenMP 1.\n\n# Limitations\n\n`ngx_small_light` has the limitations below.\n\n## Not supported features with Imlib2\n\nThe transformation with Imlib2 does not support to write GIF-image.\nBecause Imlib2 has the function for loading GIF-image but does not have the function for saving.\nAdditionally, the transformation by Imlib2 does not support to write and read WebP-image.\nSo `of=gif` and `e=imlib2` are not enabled to specify at once.\nIf these are specified, `ngx_small_light` returns 415(Unsupported Media Type).\n\n## Not supported features with GD\n\nThe transformation with GD supports to write WebP-image. But it is the experimental feature.\n\n## Not supported animated GIF\n\n`ngx_small_light` does not support the transformation kept animation for animated GIF.\nBecause it takes long time to transform(e.g. resize, crop) animated GIF kept animation.\nSo it is not realistic for `ngx_small_light` to support an animated GIF.\n\nIf the animated GIF is given, `ngx_small_light` transforms only the first frame.\n\n# Running Tests\n\n```sh\nperl Build.PL\ncpanm --installdeps .\nNGINX_BIN=${nginx_prefix_dir}/sbin/nginx ./Build test\n# or\nNGINX_BIN=${nginx_prefix_dir}/sbin/nginx prove t/**/*.t\n```\n\n# License\n\nPlease read the [COPYING](https://github.com/cubicdaiya/ngx_small_light/blob/master/COPYING).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcubicdaiya%2Fngx_small_light","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcubicdaiya%2Fngx_small_light","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcubicdaiya%2Fngx_small_light/lists"}