Tea Processing

Browser image processing with support for webp compression. Made for the purpose of reducing server load and hosting costs by offloading image processing to the client's browser.

Index

• Requirements
• Features
• Setup
  • Vanilla HTML/JavaScript
  • ReactJS
  • NodeJS
• API
  • Get Blob
  • Compress
  • Apply Ratio
  • Scale
  • Crop
  • Get Dimensions
  • Get Ratio
• Examples
  • Get Blob
  • Compress
  • Apply Ratio
  • Scale
  • Crop
  • Get Dimensions
  • Get Ratio

Requirements

• WASM support
• Canvas support

Features

• Webp compression (Implemented with Google's official codec)
• Scaling
• Cropping
• Aspect ratio

Setup

Vanilla HTML/JavaScript

• Download the files (tea-processing.js and webp directory) from GitHub and add them to your project (make sure to maintain the directory structure).

• Create the main JavaScript file and import the library

import {compress, crop, etc} from "tea-processing.js";

• Include the main js file as a module.

<script src="main.js" type="module"></script>

ReactJS

• Install the npm package

npm i tea-processing

• Import the package in your code

import {compress, crop, etc} from "tea-processing";

API

getBlob(imgFile)

Returns a Promise<Blob> with the image data.

imgFile

Type: File

compress(imgBlob, quality?)

Returns a Promise<Blob> with the compressed image data.

imgBlob

Type: Blob

quality (optional)

Type: number
Default: 75

applyRatio(imgBlob, ratio, targetResolution?)

Returns a Promise<Blob> with the image data that's been cropped to right the desired ratio.

imgBlob

Type: Blob

ratio

Type: Float

targetResolution (optional)

Type: object | null { px:number, dimension:string = "width" or "height" }
Determines the desired width or height in pixels to scale to.

scale(imgBlob, px, on)

Returns a Promise<Blob> with the image data that's been scaled up or down, to meet the desired resolution on either the width or height, while maintaining the original aspect ratio.

imgBlob

Type: Blob

px

Type: number

on

Type: string = "width" | "height"

crop(imgBlob, cropOptions)

Returns a Promise<Blob> with the image data that's been cropped.

imgBlob

Type: Blob

cropOptions

Type: object { top?:number, right?:number, bottom?:number, left?:number }
Example: If you wanted to crop 20px from the top, and 3px from the right, you would pass { top:20, right:3 }

getDimensions(imgBlob)

Returns a Promise<object> { width: number, height: number } with the images width and height in pixels

imgBlob

Type: Blob

getRatio(imgBlob)

Returns a Promise<float> with the images aspect ratio

imgBlob

Type: Blob

Examples

Get Blob

//e.target is referencing a HTML file input
let imgBlob = await getBlob(e.target.files[0])

Compress

//compress to 50% quality
imgBlob = await compress(imgBlob, 50)

Apply Ratio

A target height of 1080 at a ratio of 16/9 will produce an image with a resolution of 1920 by 1080 pixels.

imgBlob = await applyRatio(imgBlob, 16/9, { px:1080, dimension:"height" })

Scale

NOTE: if you're using Apply Ratio, it's more reliable to use the built-in scaling parameter that's provided by Apply Ratio rather than the scale function

imgBlob = await scale(imgBlob, 1080, "height")

Crop

imgBlob = await crop(imgBlob, { left: 40, right: 20 })

Get Dimensions

const dimensions = await getDimensions(imgBlob)

Get Ratio

//container is referencing a HTML div
const ratio = await getRatio(imgBlob)
container.setAttribute("style", `aspect-ratio: ${ratio};`)