# Basics
LibPixel is a real time image manipulation service for images that are publicly accessible over the internet. You can use LibPixel if your application is dealing with large number of images that need to be delivered quickly and have to be processed before reaching the user.
To get started, all you need is a LibPixel account and you can sign up for free [here](https://dashboard.libpixel.com/users/sign_up).
## How it works
LibPixel works by fetching images from an existing Image Source, processing them on the fly and responding with the modified image.
You simply supply the image size or processing you want to perform, in the query string, in the URL that you use for the image (perhaps in an `![]()
` tag). LibPixel does the rest.
**`
`**
LibPixel is designed to be fast. It is likely that the transit/download time will be far more significant than the time taken by LibPixel to process the image, so in practice processed images are delivered **as fast or faster** (due to caching and CDN) than the original image.
You never have to upload your images to LibPixel, so you retain full control over storage. You only need to store the original images, not any modified versions. LibPixel modifies the provided original images on the fly when requested.
### Supported images
The image formats supported by LibPixel are **JPEG**, **PNG**, **GIF** and **WebP**. The output image type will be the same as the input type.
By default we limit source images to a maximum of **16 megapixels** and **16 megabytes**. If you need higher limits, please [contact us](mailto:support@libpixel.com).
# Quick Start
Getting started with using LibPixel is easy. You just need to signup, provide an image source and you can start serving and processing images with LibPixel
## Signing Up
The first step towards using LibPixel's awesome features is to signup [here](https://dashboard.libpixel.com/users/sign_up). Carefully select your organisation's name, subdomain and provide your email. Also setup a secure password to protect your LibPixel account from unauthorised access.
{% hint style="warning" %}
Please select your subdomain carefully, it will be used to serve images after defining image sources. To change it afterwards, you'll need to contact our support.
{% endhint %}
After signing up and confirming the email via the link sent to your email, you can start using LibPixel.
## Create Your First Source
Now the only thing left to do before you can start serving images with LibPixel is **defining the source** of your images. To do this, press the **Create Source** button that will be present on your home screen after signing up and verifying your email address.
You'll be redirected to a form that will ask you enter the relevant information of your image source. Carefully fill out this information!
{% hint style="info" %}
Select the region closest to your source not the users. LibPixel will take care of delivering images to your users via the closest CDN.
{% endhint %}
There are two types of image sources to select from. You can either provide a public URL to the images or, you can provide access to a private S3 bucket that stores your images. There are additional steps required if you are adding a **private S3 bucket** and you can read about these steps on the [Image Sources](/setup/image-sources#s3-image-source) page.
{% hint style="success" %}
After setting up the source, you are ready to start using LibPixel to serve and process the images present in **Image Source**.
{% endhint %}
### Creating URL Source
The **Path** define the route where the image source that you will define below will be available through LibPixel. Suppose you have images similar to the following URL:
```
https://www.example-source.com/images/giraffe.png
```
Then you will enter the following URL in the **Base URL** field of the New Source form:
{% hint style="warning" %}
The **Base URL** must end with a trailing slash
{% endhint %}
Now you can access the images present in the base URL with the help of LibPixel. If you have defined the **path** as `images` then your LibPixel URL for the image mentioned above will be:
```
https://www.your-awesome-domain.libpx.com/images/giraffe.png
```
Learn how to create an AWS S3 bucket source in the [image sources](/setup/image-sources#s3-image-source) page.
## Serving Images
There are two ways of serving images while using LibPixel:
#### Using Predefined Image Sources
After configuring an image source as defined in the preceding section, you can access all images with the **path** you configured during the source creation process.
#### Using Secure URLs (Src Parameter)
The second way of using LibPixel's service is to use Secure URL's. Using this technique, you can access any public image through LibPixel. Consider the same image as in the previous section:
```
https://www.example-source.com/images/giraffe.png
```
However, this time we're not adding this as an image source and will directly access it. We can do this by building a URL as follows and appending processing queries to it.
```
?src=https%3A%2F%2Fwww.example-source.com%2Fimages%2Fgiraffe.png?blur=5
```
The last step is to secure this URL by using the [Generate Secure URLs](https://dashboard.libpixel.com/secure_urls) tool of LibPixel.
{% hint style="warning" %}
If you are manually creating such URLs then you will have to escape the source URL. Our client libraries automatically encode URLs.
{% endhint %}
The final URL that you can use in `![]()
` tags will be produced by the secure URL generator and will look like:
```
```
{% hint style="info" %}
The above shown request blurs the giraffe image by a scale of 5
{% endhint %}
# Image Sources
LibPixel supports two modes of fetching original images: pre-defined **Image Sources** or via a **`src` query string** parameter.
You can use both modes simultaneously with a single LibPixel account. To get started, create an account on [LibPixel](https://www.libpixel.com/) and follow the **Create Source** screen.
## Image Source
An Image Source is the perfect solution for when your images have a common base URL. For example, when your images are stored in an S3 bucket or on your dedicated web server.
There are two types of image sources: **URL** and **S3**.
### URL Image Source
The simplest way to use LibPixel is by providing a URL to where your images are located. It can be on a dedicated server, a public S3 storage account or any other source. It just needs to be publicly accessible.
To create a URL Image Source, press on **Create Source** and select the **Type** as **URL.** Now enter the **Path** and the **Base URL** and you are ready to start using LibPixel.
In the above image, `example.com/images` is the route to our private server that hosts our image library. After creating this source, we can access all images that are stored in the `images` via LibPixel by using the **Path** defined earlier.
Here it's `robor.libpx.com/images` and from this **Path** you can get the images delivered faster and processed according to the parameters you define.
### S3 Image Source
The S3 image source allows you to access private objects inside an S3 bucket, by entering the bucket name and the S3 region where the bucket is located.
You'll need to generate an IAM user for LibPixel with access to the S3 bucket you want to use. Please do not use your own IAM credentials for LibPixel, or those of a user with more permissions than the minimum required.
#### Setting IAM Policy
To be able to fetch your private objects, the only permission we need is `s3:GetObject`. An example IAM Policy to allow `S3:GetObject` on a specific bucket (named `libpixel-uploads` here, which you must modify to your own bucket name) is:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LibPixel",
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::libpixel-uploader/*"
]
}
]
}
```
If you wish to use the [LibPixel Uploader](https://github.com/libpixel/libpixel-uploader) library, you must choose "Enable uploads", and set an ACL (Access Control List) for uploaded images. Set to *public-read* to make uploaded files publicly accessible through S3, or *private* to make them accessible only through LibPixel.
For the uploads to work, we need the additional permissions `s3:PutObject` and `s3:PutObjectAcl`. For example:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LibPixel",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": [
"arn:aws:s3:::libpixel-uploader/*"
]
}
]
}
```
You can learn more about AWS IAM User Policies using this [link](https://docs.aws.amazon.com/AmazonS3/latest/dev/walkthrough1.html).
#### Creating an S3 Source
After creating the IAM user, the next and the final step is to create the source through LibPixel dashboard. If you are already logged in the LibPixel website then use this [link](https://dashboard.libpixel.com/sources/new) to go to the **Add New Source** form.
Provide the path at which your images will be available through LibPixel, insert the bucket name, access key ID and the secret access key to get started with serving images through LibPixel.
{% hint style="info" %}
You can check **Enable uploads**, if you want to upload images to your bucket. But, make sure your IAM user has the appropriate permissions to upload to the bucket.
{% endhint %}
## The SRC Parameter
Using the `src` query string parameter makes the most sense when images are fetched from multiple different domains. A good example is an application or website where users submit image URLs, which you wish to resize or modify before displaying them.
The value of the `src` parameter needs be escaped correctly (e.g. in JavaScript by using `encodeURIComponent`). But, if you are using any of the LibPixel Client Libraries then you do not have to worry about it since they handle it automatically.
You must sign your URLs when using the `src` parameter. This is to prevent third parties from using your LibPixel account for their own purposes. You can use [Secure URL Generator](https://dashboard.libpixel.com/secure_urls) for this purpose.
{% content-ref url="/pages/-M4Occh0xmDiMVsdtQqD" %}
[Secure URLs](/setup/secure-urls)
{% endcontent-ref %}
### Using the SRC Parameter
Suppose you want to process an image with the URL:
```
https://abcd.somewhere.com/images/header.png
```
Normally, you would just include this URL in the `src` tag of an `img` element like:
```
```
However, to use the services of LibPixel and process it before presentation, you can use the following code and process it as you like:
```
```
**Note:** You have to encode the source URL before using it in the src parameter. You can use this tool provided by [w3school](https://www.w3schools.com/tags/ref_urlencode.ASP) for encoding and decoding of URLs.
# Secure URLs
## Secure URLs
Secure URLs prevent others from generating LibPixel image URLs on your behalf, which would count toward your usage limits.
Secure URLs contain an additional `signature` parameter at the end of the query string. Signatures are generated using your private Auth Secret.
By default, signatures are only required when using the `src` parameter. To enforce signatures for all requests, visit the Settings page and enable *Require Authenticated Requests*.
### Generating Signatures
The easiest way to generate Secure URLs is by using a [**LibPixel Client Library**](/api-documentation/libraries). However, if one doesn't exist for the programming language you're using, you can generate the signatures yourself.
Steps for generating a signature:
1. Generate an image URL as normal.
2. Extract the path and query string from the URL. This is the data you'll be signing. The path must begin with a `/`, and must at least contain 1 character.
3. Generate an HMAC-SHA1 in hexadecimal format using your Auth Secret. This is your signature value.
4. Append a query string parameter `signature` with the signature value to the end of the original query string.
{% hint style="warning" %}
Include the `?` character between the path and query string components, but only if there is a query string.
If you signed a URL without a query string, then you must add a query string to the resulting URL which contains only the signature.
For example:
`https://yourdomain.libpx.com/?src=https://abcd.somewhere.com/images/header.png&width=200`
You would sign the string:
`?src=https://abcd.somewhere.com/images/header.png&width=200`.
If you are using the **src parameter** then it is important to escape the source URL properly. Our client libraries do this automatically.
{% endhint %}
# Image API
The Image API works via query string parameters.
In order to request images of the correct width, height or processed in other ways, you simply add the relevant parameters to the URL. For example, to stretch an image to fill a 200 x 200 pixel box, you would use a URL like this: `https://yourdomain.libpx.com/my-images/avatar.jpg?width=200&height=200&mode=stretch`.
Each parameter is described below. You can specify the parameters in any order.
### Width
Specifies the width of the output image in pixels.
If this value is omitted or set to 0 (default) its value will be automatically calculated based on the supplied [height](https://libpixel.com/docs/#height) value, so that the original image aspect ratio is preserved. If neither width nor height is defined, the original image size is used. And if both width and height are supplied, the image will be resized according to the [mode setting](https://libpixel.com/docs/#mode).
While there is no maximum value for width, the output image will not exceed 6 megapixels (\~2508x2508 if the image is a square). If the output image would exceed the limit, it will be scaled down automatically to the largest supported size.
### Height
Specifies the height of the output image in pixels.
If this value is omitted or set to 0 (default) its value will be automatically calculated based on the supplied [width](https://libpixel.com/docs/#width) value, so that the original image aspect ratio is preserved. If neither width nor height is defined, the original image size is used. And if both width and height are supplied, the image will be resized according to the [mode setting](https://libpixel.com/docs/#mode).
While there is no maximum value for height, the output image will not exceed 6 megapixels (\~2508x2508 if the image is a square). If the output image would exceed the limit, it will be scaled down automatically to the largest possible supported size.
### Mode
Controls the resize mode when both a [width](https://libpixel.com/docs/#width) and [height](https://libpixel.com/docs/#height) are specified.
Available modes:
* `fit`: Resize to fit within the boundaries defined by the `width` and `height` parameters, while maintaining the original aspect ratio. If the output aspect ratio differs from the original, only one of the dimensions (width or height) will equal its set value, while the other will be smaller.
* `crop`: Resize to fill the entire area defined by `width` and `height`, by maintaining the aspect ratio, but possibly clipping part of the image.
* `stretch`: Resize to fill the entire area defined by `width` and `height`, by modifying the aspect ratio.
The default mode is `fit`.
### Crop
Allows you to specify which part of the image is used.
To crop an image, you specify four parameters – the origin x and y (which defines the top left of the crop rectangle) and the dimensions w and h (which define the size of the rectangle).
Cropping is applied before other transformations. In particular, the crop values refer to the dimensions of the image before it has been resized. Note also that resizing may cause additional cropping of some part of the image if `mode=crop` is used.
The default mode is `fit`.
### DPR
Specifies the device pixel ratio, between `0.1` and `10.0`.
Acts as a multiplier for both the width and height. For example, using `width=320&height=150&dpr=2` is equivalent to `width=640&height=300`.
This allows you to easily specify an image with the correct resolution for high dpi devices such as iPhones.
The default DPR is `1.0`.
### Blur
Blurs the image by a value relative to the image size, between `0` and `100`.
The maximum blur radius (r) in pixels which corresponds to a blur value of 100 is calculated using the following formula for the image width (w) and height (h):
For a 640x480 pixel image, a blur value of 100 translates into a blur radius of 80 pixels.
This guarantees that the same blur value will result in the same level of blurriness for the same image at different sizes.
The default blur value is `0` (no blur).
### Brightness
Adjusts the brightness of the image, with values between `-100` and `100`.
The default value is `0` (no brightness adjustment).
### Contrast
Adjusts the contrast of the image, with values between `-100` and `100`.
The default value is `0` (no contrast adjustment).
### Hue
Adjusts the hue of the image, with values between `-100` and `100`.
The default value is `0` (no hue adjustment).
### Saturation
Adjusts the saturation of the image, with values between `-100` and `100`.
A saturation value of `-100` turns the image into grayscale.
The default value is `0` (no saturation adjustment).
### Gamma
Adjusts the gamma of the image, with values between `-100` and `100`.
The default value is `0` (no gamma adjustment).
### Quality
Sets the quality of the output image, with values between `0` and `100`.
This setting only affects JPEG images. Higher quality values result in images with a larger file size.
The default quality is `85`.
### Format
Normally images are processed and presented in the same format as the input image. This parameter allows you to force the output image to a particular format.
You can force images to be output as *jpeg*, *png* or *webp*, using `format=jpeg`, `format=png` or `format=webp`.
If the original image has an alpha channel (e.g. transparent PNGs), a white background will be applied if the output format does not support transparency.
### Upscale
Defines whether the image can be resized past its original size. Set to `false` to prevent upscaling.
The default upscale value is `true`.
### Debug
When LibPixel encounters an error processing an image it may still return a valid image. For example, when using a query string parameter value that's invalid, LibPixel may choose to use a default value or clamp it to the accepted range.
To see an error message instead (as an image), you can set the `debug=true` query string parameter.
### Pass through parameters
If you wish to pass query string parameters to your server or image source, just prefix them with an underscore. LibPixel will strip the underscore and pass the parameter along when the image is fetched. For example:
`https://yourdomain.libpx.com/my-images/avatar.jpg?width=200&_user=247`
would cause LibPixel to fetch the image from the following URL:
`https://my.image.source.com/images/avatar.jpg?user=247`
(The image source in this case is `https://my.image.source.com/images/`)
# Libraries
We have official client libraries built for multiple programming languages. All our libraries are open source under the MIT License and available on GitHub.
* [Go](https://github.com/libpixel/libpixel-go)
* [JavaScript](https://github.com/libpixel/libpixel-js)
* [Ruby](https://github.com/libpixel/libpixel-ruby)
* [Crystal](https://github.com/libpixel/libpixel.cr)
* [React](https://github.com/libpixel/react-libpixel)
These libraries contain helper functions that will allow you to start using LibPixel in your projects without having to spend time building simple methods. The libraries contain code for creating URLs and adding custom properties to the images to change the output image. This will help you serve images from LibPixel in your projects, resulting in increased performance and SEO metrics.
For more please visit our [Github page](https://github.com/libpixel).
# libpixel.js
libpixel.js allows developers to use the services of LibPixel in their web applications without having to rely on other dependencies. The service allows you to generate and sign URLs.
## Introduction
With the help of `libpixel.js` you can generate responsive images by defining the paremeters and letting the library generate the signed URLs. The generated and signed URLs can be used by setting the `src` attribute of the `img` element. `picture` element can be used to create a more responsive system that loads specific images according to the resolution and orientation of devices.
## Install
There are two ways to install `libpixel.js`:
1: **npm**: `$ npm install libpixel`
2: **Manually**: Download the [latest release](https://github.com/libpixel/libpixel-js/releases) and use the JavaScript files in the `src` folder.
## Usage
`libpixel.js` is pretty simple to get started with. You just start by requiring the module and creating an instance of the client. The only required attribute is `host`, which should contain your LibPixel `domain` that you will setup while [signing up](https://dashboard.libpixel.com/users/sign_up).
```javascript
var LibPixel = require("libpixel");
var libpx = new LibPixel({ host: "your-domain.libpx.com" });
```
In addition to `host`, the following attributes are supported:
* `secret`: Auth secret for your LibPixel account. Required for signing requests.
* `https`: Generate HTTPS URLs. Default is `false`.
After initializing the LibPixel client, you are ready to start using `libpixel.js`. With the help of it, you can sign existing URLs to enable LibPixel support by using the `sign()` method, or you can generate and sign new URLs at the same time by using the `url()` method of the LibPixel client.
Regardless of what method you use, the output will be a signed URL, which can then use in the `src` attribute of your `img` elements to provide processed images that meet your requirements.
### Sign URLs
You can sign an existing URL using the `sign()` method:
```javascript
var url = libpx.sign("http://test.libpx.com/images/1.jpg?width=400");
```
### Generate URLs
You can also generate and sign URLs at the same time with the `url()` method:
```javascript
var url = libpx.url("/images/1.jpg", { height: 400, blur: 20, saturation: -80 });
```
## License
`libpixel.js` is owned by [LibPixel](https://www.libpixel.com/) and is licensed under the [MIT](https://app.gitbook.com/s/-M4OVwLnfB0xsqOJcSjm/api-documentation/libraries/LICENSE) license. Contributions are welcomed.
