UpscalerJS

https://upscalerjs.com/documentation
Admin
UpscalerJS is a JavaScript library for enhancing and upscaling images using AI-powered neural...
Tokens:12,691
Snippets:191
Trust Score:5.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Electron Example Dependencies

Source: https://upscalerjs.com/documentation/guides/other/electron

Navigate to the electron example directory and install required packages.

```bash
cd UpscalerJS/examples/electron
npm install
```

--------------------------------

### Install Dependencies for Cloudflare Worker Example

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

Navigate to the cloudflare-worker example directory and install its dependencies.

```bash
cd UpscalerJS/examples/cloudflare-worker  
npm install  
```

--------------------------------

### Node.js tfjs-node Setup

Source: https://upscalerjs.com/documentation/getting-started

Install and initialize UpscalerJS for the standard Node.js environment.

```bash
npm install upscaler @tensorflow/tfjs-node  
```

```javascript
const Upscaler = require('upscaler/node');  
const upscaler = new Upscaler();  
upscaler.upscale('/image/path').then(upscaledSrc => {  
  // base64 representation of image src  
  console.log(upscaledSrc);  
});  
```

--------------------------------

### Node.js tfjs-node-gpu Setup

Source: https://upscalerjs.com/documentation/getting-started

Install and initialize UpscalerJS for the GPU-accelerated Node.js environment.

```bash
npm install upscaler @tensorflow/tfjs-node-gpu  
```

```javascript
const Upscaler = require('upscaler/node-gpu');  
const upscaler = new Upscaler();  
upscaler.upscale('/image/path').then(upscaledSrc => {  
  // base64 representation of image src  
  console.log(upscaledSrc);  
});  
```

--------------------------------

### NPM Installation and Usage

Source: https://upscalerjs.com/documentation/getting-started

Install UpscalerJS and its dependencies via NPM.

```bash
npm install upscaler @tensorflow/tfjs  
```

```javascript
import Upscaler from 'upscaler'  
const upscaler = new Upscaler()  
```

```bash
npm install @upscalerjs/esrgan-thick  
```

--------------------------------

### Start Browser Frontend

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

Run this command in one terminal to start the browser frontend.

```bash
npm run browser:start  
```

--------------------------------

### Start Electron Application

Source: https://upscalerjs.com/documentation/guides/other/electron

Launch the Electron application locally.

```bash
npm run start
```

--------------------------------

### Quick Start Browser Usage

Source: https://upscalerjs.com/documentation/getting-started

Basic implementation for browser environments using the UpscalerJS library.

```javascript
// browser-only; see below for Node.js instructions  
import Upscaler from 'upscaler';   
const upscaler = new Upscaler();  
upscaler.upscale('/image/path').then(upscaledSrc => {  
  // base64 representation of image src  
  console.log(upscaledSrc);  
});  
```

--------------------------------

### Install UpscalerJS model

Source: https://upscalerjs.com/documentation/guides/browser/models

Use npm to install the desired model package.

```bash
npm install @upscalerjs/esrgan-thick
```

--------------------------------

### Define model setup and teardown hooks

Source: https://upscalerjs.com/documentation/guides/browser/usage/custom-model-configurations

Includes setup and teardown functions for registering custom layers or managing memory.

```javascript
import Upscaler from 'upscaler'  
  
const upscaler = new Upscaler({  
  model: {  
    scale: 2,  
    path: '/model.json',  
    preprocess: input => tf.tidy(() => tf.mul(input, 1 / 255)),  
    postprocess: output => tf.tidy(() => output.clipByValue(0, 255)),  
      /**  
       * tf refers to the currently active Tensorflow.js library, which may be   
       * @tensorflow/tfjs, @tensorflow/tfjs-node, or @tensorflow/tfjs-node-gpu.  
       **/  
    setup: async (tf) => {  
      class CustomLayer extends Layer {  
        call(inputs: Inputs) {  
          ... some definition ...  
        }  
  
        static className = 'CustomLayer'  
      }  
  
      tf.serialization.registerClass(CustomLayer);  
    },  
    teardown: async (tf) => {  
      // release some memory  
    }  
  },  
})  
```

--------------------------------

### Import ESRGAN-Thick Model

Source: https://upscalerjs.com/documentation/guides/node/nodejs-model

Import the 2x scale version of the model from the installed package.

```javascript
const x2 = require('@upscalerjs/esrgan-thick/2x')
```

--------------------------------

### Script Tag Installation

Source: https://upscalerjs.com/documentation/getting-started

Include UpscalerJS via CDN script tags in an HTML file.

```html
<script src="https://cdn.jsdelivr.net/npm/@upscalerjs/default-model@latest/dist/umd/index.min.js"></script>  
<script src="https://cdn.jsdelivr.net/npm/upscaler@latest/dist/browser/umd/upscaler.min.js"></script>  
```

--------------------------------

### Clone UpscalerJS Repository

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

Clone the UpscalerJS repository to access example code.

```bash
git clone https://github.com/thekevinscott/UpscalerJS.git  
```

--------------------------------

### Start Cloudflare Worker Backend

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

Run this command in another terminal to start the local Cloudflare worker backend.

```bash
npm run wrangler:start  
```

--------------------------------

### Initialize UpscalerJS with a Model

Source: https://upscalerjs.com/documentation/guides/browser/basic-umd

When using UpscalerJS via a script tag, you must explicitly provide a model. This example uses the 'DefaultUpscalerJSModel'.

```javascript
const upscaler = new Upscaler({
  model: DefaultUpscalerJSModel,
})

```

--------------------------------

### GET /getModel

Source: https://upscalerjs.com/documentation/api/getModel

Retrieves the model package currently in use by the Upscaler instance.

```APIDOC
## getModel

### Description
Gets the model package currently loaded in the Upscaler instance.

### Returns
- **Promise<ModelPackage>** - A promise that resolves to a modelPackage object containing the following fields:
  - **model** (tf.LayersModel) - The underlying TensorFlow.js model.
  - **modelDefinition** (ModelDefinition) - The definition object for the model.

### Request Example
```javascript
const upscaler = new Upscaler();
upscaler.getModel().then(modelPackage => {
  console.log(modelPackage);
});
```
```

--------------------------------

### Customize Progress Output Format

Source: https://upscalerjs.com/documentation/guides/browser/usage/progress

Control the output format of the `imageSlice` received in the progress callback using `progressOutput`. This allows you to get slices in a different format (e.g., 'base64') than the final upscale output (e.g., 'tensor').

```javascript
upscaler.upscale(image, {
  output: 'tensor',
  progressOutput: 'base64',
  progress: (percent, slice) => {
    // our slice will now be a base64 src, even though the response
    // from upscale will be a tensor
    console.log(slice)
  }
})
```

--------------------------------

### Initialize Upscaler with a custom model path

Source: https://upscalerjs.com/documentation/guides/browser/usage/custom-model-configurations

Basic configuration requiring a path to a locally accessible model.json file.

```javascript
import Upscaler from 'upscaler'  
  
const upscaler = new Upscaler({  
  model: {  
    path: '/model.json',  
  }  
})  
```

--------------------------------

### Warm up with patch size and padding

Source: https://upscalerjs.com/documentation/guides/browser/performance/warmup

Configure warmup using specific patch dimensions and padding values.

```javascript
upscaler.warmup({ patchSize: 64, padding: 2 })  
```

```javascript
upscaler.warmup([{ patchSize: 64, padding: 2 }, { patchSize: 32, padding: 2 }])  
```

--------------------------------

### Initialize and warm up an UpscalerJS model

Source: https://upscalerjs.com/documentation/guides/browser/performance/warmup

Basic implementation showing model initialization and the warmup method call.

```javascript
import Upscaler from 'upscaler'  
  
const upscaler = new Upscaler()  
  
upscaler.warmup({ patchSize: 64, padding: 2 }).then(() => {  
  console.log('All warmed up')  
})  
```

--------------------------------

### Warm up an Upscaler instance

Source: https://upscalerjs.com/documentation/api/warmup

Initializes the model with a specified patch size and padding configuration.

```typescript
const upscaler = new Upscaler();  
upscaler.warmup([{  
  patchSize: 64,  
  padding: 2,  
}]).then(() => {  
  console.log('All warmed up!');  
});  
```

--------------------------------

### Instantiate UpscalerJS in Cloudflare Worker

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

Import necessary libraries and instantiate UpscalerJS with a model within the Cloudflare Worker script. The '@upscalerjs/esrgan-slim' model is recommended for the free tier.

```javascript
// cloudflare-worker script  
import * as tf from '@tensorflow/tfjs'
import Upscaler from 'upscaler'
import model from '@upscalerjs/esrgan-slim/4x'
const upscaler = new Upscaler({
  model,
})

```

--------------------------------

### Instantiate UpscalerJS with a Model

Source: https://upscalerjs.com/documentation/api/constructor

Instantiates an UpscalerJS instance with a specified model and warmup sizes. Ensure the model is imported before use.

```javascript
import Upscaler from 'upscaler';
import x2 from '@upscalerjs/models/esrgan-thick/2x';

const upscaler = new Upscaler({
  model: x2,
  warmupSizes: { patchSize: 64 },
});

```

--------------------------------

### Warm up with numeric sizes

Source: https://upscalerjs.com/documentation/guides/browser/performance/warmup

Provide numeric values to define the width and height for model warmup.

```javascript
upscaler.warmup(64)  
```

```javascript
upscaler.warmup([64, 32])  
```

--------------------------------

### Clone UpscalerJS Repository

Source: https://upscalerjs.com/documentation/guides/other/electron

Initial step to retrieve the project source code.

```bash
git clone https://github.com/thekevinscott/UpscalerJS.git
```

--------------------------------

### Upscale images in Node.js

Source: https://upscalerjs.com/documentation/guides/node/nodejs

Demonstrates the standard workflow for loading an image, upscaling it, and saving the result in a Node.js environment. Ensure the use of upscaler/node and proper disposal of tensors to prevent memory leaks.

```javascript
const tf = require('@tensorflow/tfjs-node')  
const Upscaler = require('upscaler/node') // this is important!  
  
const upscaler = new Upscaler()  
const image = tf.node.decodeImage(fs.readFileSync('/path/to/image.png'), 3)  
const tensor = await upscaler.upscale(image)  
const upscaledTensor = await tf.node.encodePng(tensor)  
fs.writeFileSync('/path/to/upscaled/image.png', upscaledTensor)  
  
// dispose the tensors!  
image.dispose()  
tensor.dispose()  
upscaledTensor.dispose()  
```

--------------------------------

### Configure Patch Size and Padding

Source: https://upscalerjs.com/documentation/getting-started

Provide `patchSize` and `padding` parameters to infer the image in patches, preventing UI blocking. Padding is necessary to avoid artifacting at patch seams.

```javascript
({  
  patchSize: 64,  
  padding: 5,  
})
```

--------------------------------

### Script Tag Initialization

Source: https://upscalerjs.com/documentation/getting-started

Initialize UpscalerJS when using the script tag approach.

```html
<script type="text/javascript">  
  const upscaler = new Upscaler({  
    model: DefaultUpscalerJSModel,  
  })  
</script>  
```

--------------------------------

### Initialize Upscaler with custom model

Source: https://upscalerjs.com/documentation/guides/browser/models

Pass the imported model object into the Upscaler constructor configuration.

```javascript
import Upscaler from 'upscaler'
const upscaler = new Upscaler({
  model: x2,
})
```

--------------------------------

### UpscalerJS Constructor

Source: https://upscalerjs.com/documentation/api/constructor

Instantiates an instance of UpscalerJS with model configuration and warmup parameters.

```APIDOC
## Constructor: new Upscaler(opts)

### Description
Instantiates an instance of UpscalerJS.

### Parameters
#### Request Body
- **opts** (object) - Required - Configuration options for the upscaler.
  - **model** (object) - Optional - Model configuration. Defaults to @upscalerjs/default-model.
    - **modelType** (string) - Optional - The type of the model ('graph' or 'layer'). Defaults to 'layer'.
    - **path** (string) - Optional - Path to a model.json file.
    - **scale** (number) - Optional - The scale of the model.
    - **preprocess** (function) - Optional - Function to process input image before inference.
    - **postprocess** (function) - Optional - Function to process output image after inference.
    - **inputRange** (Range) - Optional - Expected input range. Defaults to [0, 255].
    - **outputRange** (Range) - Optional - Expected output range. Defaults to [0, 255].
    - **divisibilityFactor** (number) - Optional - Divisibility requirement for input images.
    - **setup** (function) - Optional - Function that runs when model is instantiated.
    - **teardown** (function) - Optional - Function that runs when model is disposed.
  - **warmupSizes** (WarmupSizes) - Optional - Configuration for warmup sizes.

### Request Example
```javascript
import Upscaler from 'upscaler';
import x2 from '@upscalerjs/models/esrgan-thick/2x';

const upscaler = new Upscaler({
  model: x2,
  warmupSizes: { patchSize: 64 },
});
```

### Response
- **Returns** (Upscaler) - An instance of an UpscalerJS class.
```

--------------------------------

### Instantiate UpscalerJS

Source: https://upscalerjs.com/documentation/guides/browser/basic-npm

Create a new instance of the Upscaler class. This instance will be used to perform image upscaling operations.

```javascript
const upscaler = new Upscaler();
```

--------------------------------

### Initialize UpscalerJS in React App.js

Source: https://upscalerjs.com/documentation/guides/browser/implementations/react

Imports the Upscaler library and initializes a new instance for use within the React component.

```javascript
import './App.css';
import Upscaler from 'upscaler';
import React, { useCallback, useState, useEffect, useRef } from 'react';
import { useDropzone } from 'react-dropzone';
const upscaler = new Upscaler();
function App() {
const [src, setSrc] = useState();
const [originalSize, setOriginalSize] = useState();
const [scale, setScale] = useState(1);
const [interpolation, setInterpolation] = useState('bicubic');
```

--------------------------------

### Configure Local Model Path

Source: https://upscalerjs.com/documentation/guides/other/electron

Initialize UpscalerJS with a local path to the model file to avoid remote CDN dependencies.

```javascript
import Upscaler from 'upscaler'
import defaultModel from '@upscalerjs/default-model'

const upscaler = new Upscaler({
  model: {
    ...defaultModel,
    path: './node_modules/@upscalerjs/default-model/models/model.json',
  },
})
```

--------------------------------

### Creating a Tensor from an Image

Source: https://upscalerjs.com/documentation/guides/browser/tensors

Demonstrates creating a TensorFlow.js tensor from an image source. This is useful if you need to perform additional operations on the tensor before upscaling.

```javascript
import flower from '/path/to/flower.png'  
  
const tensor = tf.browser.fromPixels(flower)  
// inspect this tensor further with:  
// tensor.print()
```

--------------------------------

### Initialize Upscaler with a Local Model

Source: https://upscalerjs.com/documentation/guides/browser/usage/self-hosting-models

Configures the Upscaler instance to load a model from a local path. The path must point to a valid model.json file accessible via HTTP.

```javascript
import Upscaler from "upscaler";
import img from "/flower.png?url";
const target = document.getElementById("target");
const button = document.getElementById("button");
const info = document.getElementById("info");
const upscaler = new Upscaler({
model: {
scale: 2,
path: '/model.json',
}
})
```

```javascript
import Upscaler from 'upscaler'  
  
const upscaler = new Upscaler({  
  model: {  
    scale: 2,  
    path: '/model.json',  
  }  
})
```

--------------------------------

### Configure model options with preprocessing and postprocessing

Source: https://upscalerjs.com/documentation/guides/browser/usage/custom-model-configurations

Adds scale, preprocessing, and postprocessing functions to manipulate input and output tensors.

```javascript
import Upscaler from 'upscaler'  
  
const upscaler = new Upscaler({  
  model: {  
    scale: 2,  
    path: '/model.json',  
    preprocess: input => tf.tidy(() => tf.mul(input, 1 / 255)),  
    postprocess: output => tf.tidy(() => output.clipByValue(0, 255)),  
  }  
})  
```

--------------------------------

### Load a custom model via file path in Node.js

Source: https://upscalerjs.com/documentation/guides/node/nodejs-custom-file-path

Configures the Upscaler instance to point to a specific model file on the local file system using tf.io.fileSystem.

```javascript
const Upscaler = require('upscaler/node')  
const upscaler = new Upscaler({  
  model: {  
    scale: 2,  
    path: tf.io.fileSystem('/path/to/model.json'),  
  }  
})  
```

--------------------------------

### Importing Dependencies for Upscaling

Source: https://upscalerjs.com/documentation/guides/browser/tensors

Imports necessary libraries for UpscalerJS and TensorFlow.js operations.

```javascript
import * as tf from '@tensorflow/tfjs';
import flower from './public/flower.png';
import Upscaler from 'upscaler';
```

--------------------------------

### Import UpscalerJS

Source: https://upscalerjs.com/documentation/guides/browser/basic-npm

Import the Upscaler class from the 'upscaler' package. This is the primary step to use the library.

```javascript
import Upscaler from "upscaler";
```

--------------------------------

### Warmup Instance

Source: https://upscalerjs.com/documentation/api/warmup

Warms up an Upscaler instance with specified patch sizes and options. This preloads the model for faster subsequent operations.

```APIDOC
## POST /upscaler/warmup

### Description
Warms up an Upscaler instance.

### Method
POST

### Endpoint
/upscaler/warmup

### Parameters
#### Request Body
- **warmupSizes** (WarmupSizes) - Required - Denotes how to warm the model up.
- **options** (object) - Optional - A set of warm up arguments.
  - **signal** (AbortSignal) - Optional - Provides a mechanism to abort the warmup process.
  - **awaitNextFrame** (boolean) - Optional - If provided, upscaler will await `tf.nextFrame()` on each cycle.

### Request Example
```json
{
  "warmupSizes": [
    {
      "patchSize": 64,
      "padding": 2
    }
  ],
  "options": {
    "awaitNextFrame": true
  }
}
```

### Response
#### Success Response (200)
- **Promise<void>** - Indicates the warmup process has completed.

#### Response Example
```json
// No response body, promise resolves on completion
```

### `WarmupSizes` Type Definition
`WarmupSizes` can be one of the following:
- `number`: A number representing both the size (width and height) of the patch.
- `{patchSize: number; padding?: number}`: An object with the `patchSize` and optional `padding` properties.
- `number[]`: An array of numbers representing the size (width and height) of the patch.
- `{patchSize: number; padding?: number}[]`: An array of objects with the `patchSize` and optional `padding` properties.
```

--------------------------------

### Configure UpscalerJS output as base64

Source: https://upscalerjs.com/documentation/guides/node/nodejs

Shows how to modify the upscale method options to return a base64 string instead of the default tensor.

```javascript
const tensor = await upscaler.upscale(image, {  
  output: 'base64',  
})  
```

--------------------------------

### Model Configuration

Source: https://upscalerjs.com/documentation/getting-started

Configure UpscalerJS with custom models or local paths.

```bash
npm install @upscalerjs/esrgan-thick  
```

```javascript
import Upscaler from 'upscaler';  
import x4 from '@upscalerjs/esrgan-thick/4x';  
const upscaler = new Upscaler({  
  model: x4,  
});  
```

```javascript
const upscaler = new Upscaler({  
  model: {  
    path: '/path/to/model',  
    scale: 2,  
  },  
});  
```

--------------------------------

### UpscalerJS Core Methods

Source: https://upscalerjs.com/documentation/api

This section covers the fundamental methods available in the UpscalerJS library for managing and executing image upscaling tasks.

```APIDOC
## UpscalerJS API

### Description
API Documentation for UpscalerJS.

### Methods

- **constructor**
  Initializes a new instance of the UpscalerJS class.

- **execute**
  Executes the image upscaling process.

- **upscale**
  Performs the image upscaling operation.

- **warmup**
  Prepares the model for faster subsequent operations.

- **abort**
  Aborts any ongoing upscaling process.

- **dispose**
  Releases resources used by the UpscalerJS instance.

- **getModel**
  Retrieves the currently loaded model.
```

--------------------------------

### Upscale with Patch Size and Padding

Source: https://upscalerjs.com/documentation/guides/browser/performance/patch-sizes

Configures the upscaler to process images in smaller patches with padding to reduce edge artifacts.

```javascript
import Upscaler from 'upscaler'  
import image from '/path/to/image.png'  
const upscaler = new Upscaler()  
upscaler.upscale(image, {  
  patchSize: 32,  
  padding: 2,  
})  
```

```javascript
upscaler.upscale(image, {  
  patchSize: 32,  
  padding: 0,  
})  
```

--------------------------------

### Handle Environment String Input Limitation

Source: https://upscalerjs.com/documentation/troubleshooting

Environments lacking access to the `Image` constructor (like web workers) cannot process string URLs directly. Pass input data as a tensor in such cases.

```javascript
Error: Environment does not support a string URL as an input format.
```

--------------------------------

### execute(image, options)

Source: https://upscalerjs.com/documentation/api/execute

Processes a given image through a specified neural network.

```APIDOC
## execute(image, options)

### Description
Processes a given image through a specified neural network. This is an alias for the `upscale` method.

### Parameters
#### Arguments
- **image** (Input) - Required - The image to enhance.
- **options** (Object) - Optional - A set of enhancing arguments.

#### Options Fields
- **signal** (AbortSignal) - Optional - Provides a mechanism to abort the warmup process.
- **awaitNextFrame** (boolean) - Optional - If provided, upscaler will await tf.nextFrame() on each cycle.
- **output** (base64 | tensor) - Optional - Denotes the kind of response UpscalerJS returns.
- **patchSize** (number) - Optional - Optionally specify an image patch size to operate on.
- **padding** (number) - Optional - Optionally specify a patch size padding.
- **progress** (Progress) - Optional - An optional progress callback if execute is called with a patchSize argument.
- **progressOutput** (base64 | tensor) - Optional - Denotes the kind of response UpscalerJS returns within a progress callback.

### Request Example
const upscaler = new Upscaler();
upscaler.execute(image, {
  output: 'base64',
  patchSize: 64,
  padding: 2,
  progress: (progress) => {
    console.log('Progress:', progress);
  }
});

### Response
- **Returns** (Promise<Tensor3D | string>) - An enhanced image.
```

--------------------------------

### Set Content-Security-Policy

Source: https://upscalerjs.com/documentation/guides/other/electron

Required meta tag to allow local resource loading and base64-encoded images in Electron.

```html
<meta http-equiv="Content-Security-Policy" content="img-src 'self' data:; default-src 'self'; script-src 'self'">
```

--------------------------------

### Provide Valid Warmup Sizes

Source: https://upscalerjs.com/documentation/troubleshooting

The `.warmup` method in UpscalerJS requires specific formats for its arguments. Ensure you are passing either an object with `patchSize` and `padding`, an array of `[width, height]`, or arrays of these formats.

```javascript
upscaler.warmup('foo')
```

--------------------------------

### Import specific model scale

Source: https://upscalerjs.com/documentation/guides/browser/models

Import the model scale required for the upscaling task.

```javascript
import x2 from '@upscalerjs/esrgan-thick/2x'
```

--------------------------------

### abort()

Source: https://upscalerjs.com/documentation/api/abort

The abort method stops all currently running asynchronous tasks within the Upscaler instance.

```APIDOC
## abort()

### Description
Aborts all active asynchronous methods, including execution and warm-up processes.

### Returns
- **void** - This method does not return a value.

### Request Example
```javascript
const upscaler = new Upscaler();
upscaler.abort();
```
```

--------------------------------

### Load Image Pixels in Browser

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

In the browser, load image pixels using TensorFlow.js.

```javascript
// browser script  
const pixels = tf.browser.fromPixels(img)  
```

--------------------------------

### Include UpscalerJS via Script Tags

Source: https://upscalerjs.com/documentation/guides/browser/basic-umd

Load TensorFlow.js, the default UpscalerJS model, and UpscalerJS itself using CDN links. Ensure these are included in your HTML to use UpscalerJS in the browser.

```html
<script src="https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@latest/dist/tf.min.js"></script>  
<script src="https://cdn.jsdelivr.net/npm/@upscalerjs/default-model@latest/dist/umd/index.min.js"></script>  
<script src="https://cdn.jsdelivr.net/npm/upscaler@latest/dist/browser/umd/upscaler.min.js"></script>  

```

--------------------------------

### Upscaling Images

Source: https://upscalerjs.com/documentation/getting-started

Perform image upscaling and configure output types.

```javascript
upscaler.upscale('/path/to/image').then(img => {  
  console.log(img);  
});  
```

```javascript
upscaler.upscale('/path/to/image', {  
  output: 'tensor',  
}).then(img => {  
  console.log(img);  
});  
```

--------------------------------

### Specify Output Format for Base64 Limitation

Source: https://upscalerjs.com/documentation/troubleshooting

Environments without access to `Image` or `document` (e.g., web workers) cannot automatically generate base64 output. Specify 'tensor' as the output format in these scenarios.

```javascript
upscaler.upscale(tensor, {
  output: 'tensor',
})
```

--------------------------------

### Execute image enhancement

Source: https://upscalerjs.com/documentation/api/execute

Processes an image using specified options and handles the resulting enhanced image via a promise.

```javascript
const upscaler = new Upscaler();  
const image = new Image();  
image.src = '/some/path/to/image.png';  
  
upscaler.execute(image, {  
  output: 'base64',  
  patchSize: 64,  
  padding: 2,  
  progress: (progress) => {  
    console.log('Progress:', progress);  
  },  
}).then(enhancedSrc => {  
  console.log(enhancedSrc);  
});
```

--------------------------------

### Configure Custom Model Path

Source: https://upscalerjs.com/documentation/troubleshooting

When providing a custom model configuration, ensure the 'path' variable is included. This specifies the location of your custom model.

```javascript
const upscaler = new Upscaler({
  model: {
    path: '/path/to/custom/model',
    ... other model configuration variables ...
  },
});
```

--------------------------------

### Upscale Image from URL

Source: https://upscalerjs.com/documentation/guides/browser/basic-npm

Upscale an image provided as a URL string. The `upscale` method returns a promise that resolves to a base64 encoded image source.

```javascript
import pathToImage from '/path/to/image.png'
  
upscaler.upscale(pathToImage)
```

```javascript
upscaler.upscale(pathToImage).then(upscaledImageSrc => {
  
  const img = document.createElement("img")  
  img.src = upscaledImgSrc  
  document.body.appendChild(img)
})
```

--------------------------------

### Upscaling with Tensor Output

Source: https://upscalerjs.com/documentation/guides/browser/tensors

Configures UpscalerJS to return the upscaled result as a tensor, offering better performance and memory control.

```javascript
upscaler.upscale(tensor, {  
  output: 'tensor',  
}).then(upscaledTensor => {  
  upscaledTensor.print()  
})
```

--------------------------------

### Specify Progress Callback Function

Source: https://upscalerjs.com/documentation/guides/browser/usage/progress

Pass a callback function to the `upscale` method to receive progress updates. This is particularly useful for large images or complex models. The `progress` callback is invoked when `patchSize` is set or for models with fixed input sizes.

```javascript
import Upscaler from 'upscaler'
import image from '/path/to/image.png'

const upscaler = new Upscaler()

upscaler.upscale(image, {
  progress: (percent) => {
    console.log(`${percent * 100}% of image has been processed`)
  }
})
```

--------------------------------

### Manual Tensor Memory Management

Source: https://upscalerjs.com/documentation/guides/browser/tensors

Shows how to manually dispose of tensors after use when working with tensor inputs or outputs to prevent memory leaks. This is crucial for performance in long-running applications.

```javascript
upscaler.upscale(tensor, {  
  output: 'tensor',  
}).then(upscaledTensor => {  
  // we are now done with our initial tensor; dispose of its memory  
  tensor.dispose()  
  
  // do something with the upscaled tensor  
  upscaledTensor.print()  
  
  // dispose of the upscaled tensor  
  upscaledTensor.dispose()  
})
```

--------------------------------

### Retrieve Model Package with getModel

Source: https://upscalerjs.com/documentation/api/getModel

Use this method to access the currently loaded model and its definition. It returns a promise that resolves to a modelPackage object.

```typescript
const upscaler = new Upscaler();  
upscaler.getModel().then(modelPackage => {  
  console.log(modelPackage);  
})  
```

--------------------------------

### POST /dispose

Source: https://upscalerjs.com/documentation/api/dispose

Disposes of an UpscalerJS instance and clears up any used memory. Ensure any active execution events have first been aborted before disposing of the model.

```APIDOC
## dispose

### Description
Disposes of an UpscalerJS instance and clears up any used memory. Ensure any active execution events have first been aborted before disposing of the model.

### Returns
- **Promise<void>** - A promise that resolves when the instance has been disposed.

### Request Example
```javascript
const upscaler = new Upscaler();
upscaler.dispose().then(() => {
  console.log("All cleaned up!");
});
```
```

--------------------------------

### Node.js Environment Syntax Error

Source: https://upscalerjs.com/documentation/troubleshooting

In a Node.js environment, encountering a 'SyntaxError: Unexpected token "export"' suggests either using the incorrect UpscalerJS package ('upscaler' instead of 'upscaler/node') or using 'import' syntax instead of 'require'.

```javascript
/node_modules/upscaler/dist/browser/esm/index.js:1
export { default, } from './upscaler';
^^^^^^

SyntaxError: Unexpected token 'export'
```

--------------------------------

### Add Explicit Padding to Resolve Artifacting

Source: https://upscalerjs.com/documentation/troubleshooting

When specifying a patch size, ensure an explicit padding value is provided to prevent artifacting in the upscaled image. If artifacting is desired, set padding to 0.

```javascript
upscaler.upscale('/path/to/img', {
  patchSize: 64,
  padding: 4,
})
```

```javascript
upscaler.upscale('/path/to/img', {
  patchSize: 64,
  padding: 0,
})
```

--------------------------------

### Receive and Reconstruct Upscaled Tensor in UI Thread

Source: https://upscalerjs.com/documentation/guides/browser/performance/webworker

Receive the serialized upscaled image data and shape in the UI thread and reconstruct it into a TensorFlow.js tensor for further use.

```javascript
// UI thread  
worker.onmessage = async (e) => {  
  const [ data, shape ] = e.data  
  const tensor = tf.tensor(data, shape)  
}  
```

--------------------------------

### Define Model Path for Model Definition

Source: https://upscalerjs.com/documentation/troubleshooting

When defining a custom model for UpscalerJS, ensure a valid 'path' argument is provided within the 'model' object. Passing null or undefined for the path will result in an error.

```javascript
const upscaler = new Upscaler({
  model: {
    path: null,
  },
})
```

--------------------------------

### Upscale Tensor in Worker

Source: https://upscalerjs.com/documentation/guides/browser/performance/webworker

Perform image upscaling using UpscalerJS within the Web Worker. Specify 'tensor' as the output format since HTMLImageElements are unavailable.

```javascript
// Worker thread  
const upscaledImg = await upscaler.upscale(tensor, {  
  output: 'tensor',  
})  
```

--------------------------------

### Upscaling an Image Tensor

Source: https://upscalerjs.com/documentation/guides/browser/tensors

Provides a tensor directly to UpscalerJS for processing. UpscalerJS automatically handles the tensor for upscaling.

```javascript
import Upscaler from 'upscaler'  
  
const upscaler = new Upscaler()  
  
upscaler.upscale(tensor).then(upscaledSrc => {  
  console.log(upscaledSrc)  
})
```

--------------------------------

### Send Upscaled Data Back to UI Thread

Source: https://upscalerjs.com/documentation/guides/browser/performance/webworker

Transform the upscaled tensor back into serializable data (shape and raw data) before sending it from the Web Worker to the UI thread.

```javascript
// Worker thread  
const upscaledShape = upscaledImg.shape  
const upscaledData = await upscaledImg.data()  
postMessage([upscaledData, upscaledShape])  
```

--------------------------------

### Load Image Data in UI Thread

Source: https://upscalerjs.com/documentation/guides/browser/performance/webworker

In the UI thread, load image pixels into a TensorFlow.js tensor and extract its raw data. This is the first step before passing data to a Web Worker.

```javascript
// UI thread  
const pixels = tf.browser.fromPixels(image)  
const data = await pixels.data()  
```

--------------------------------

### Provide Patch Size for Progress Callback

Source: https://upscalerjs.com/documentation/troubleshooting

The progress callback in UpscalerJS is only invoked when a `patchSize` is explicitly provided in the `upscale` function call. Ensure `patchSize` is set to enable progress updates.

```javascript
upscaler.upscale('/path/to/img', {
  patchSize: 64,
  progress: ...
})
```

--------------------------------

### Cancel all inflight requests

Source: https://upscalerjs.com/documentation/guides/browser/usage/cancel

Convenience method to cancel all currently running upscale requests simultaneously.

```javascript
upscaler.abort()  
```

--------------------------------

### Serialize Tensor for Fetch Request

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

Serialize a tensor into a JSON-compatible format (data and shape) for sending in a fetch request. This is necessary because tensors cannot be natively serialized to JSON.

```javascript
// browser script  
const body = JSON.stringify({
  data: Array.from(await pixels.data()),
  shape: pixels.shape,
})
const response = await fetch(CLOUDFLARE_URL, { //CLOUDFLARE_URL is the URL of the cloudflare worker
  method: 'POST',
  body,
})

```

--------------------------------

### Cancel an individual upscale request

Source: https://upscalerjs.com/documentation/guides/browser/usage/cancel

Uses an AbortController to signal cancellation of a specific upscale operation. The operation throws an AbortError when cancelled.

```javascript
import Upscaler from 'upscaler'  
import imagePath from '/path/to/image.png'  
  
const upscaler = new Upscaler()  
const abortController = new AbortController()  
upscaler.upscale(imagePath, {  
  signal: abortController.signal,  
}).catch(abortError => {  
  console.log('UpscalerJS has been aborted', abortError)  
})  
  
// at some later point in time ...  
  
abortController.abort()  
```

--------------------------------

### Dispose of Tensors in Progress Callback

Source: https://upscalerjs.com/documentation/guides/browser/usage/progress

When receiving tensors as `imageSlice` in the progress callback, you must manually dispose of them to prevent memory leaks. This is crucial for managing resources effectively.

```javascript
upscaler.upscale(image, {
  output: 'tensor',
  progress: (percent, slice) => {
    console.log(slice)

    // Now that we're done with our tensor, dispose of it
    slice.dispose()
  }
})
```

--------------------------------

### Pass Data to Web Worker

Source: https://upscalerjs.com/documentation/guides/browser/performance/webworker

Serialize image data and tensor shape before sending to the Web Worker. Tensors themselves are not directly serializable.

```javascript
// UI thread  
worker.postMessage([data, pixels.shape])  
```

--------------------------------

### Serialize Upscaled Tensor for Response

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

Serialize the upscaled tensor back into a JSON-compatible format (data and shape) for the response from the Cloudflare Worker.

```javascript
// cloudflare-worker script  
const response = {
  data: Array.from(upscaledSrc.dataSync()),
  shape: upscaledSrc.shape,
}
return new Response(JSON.stringify(response), init)

```

--------------------------------

### Dispose an UpscalerJS instance

Source: https://upscalerjs.com/documentation/api/dispose

Use this method to free up memory after an UpscalerJS instance is no longer needed. Ensure all active execution events are aborted before calling this.

```typescript
const upscaler = new Upscaler();  
upscaler.dispose().then(() => {  
  console.log("All cleaned up!");  
})  
```

--------------------------------

### Dispose UpscalerJS Instance

Source: https://upscalerjs.com/documentation/guides/browser/performance/memory-management

Clean up an UpscalerJS instance when it's no longer needed. This method returns a promise that resolves once all memory is freed and inflight requests are aborted.

```javascript
import Upscaler from 'upscaler'
const upscaler = new Upscaler()

upscaler.dispose().then(() => {
  console.log('UpscalerJS is cleaned up')
})
```

--------------------------------

### Unserialize Tensor in Browser from Worker Response

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

In the browser, unserialize the tensor data received from the Cloudflare Worker and render it to a canvas.

```javascript
// browser script  
const { data, shape } = await response.json()
const tensor = tf.tensor(data, shape)
await tf.browser.toPixels(tensor, canvas)

```

--------------------------------

### Upscale Tensor in Cloudflare Worker

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

Pass the unserialized tensor to UpscalerJS and specify 'tensor' as the output format.

```javascript
// cloudflare-worker script  
const upscaledSrc = await upscaler.upscale(input, {
  output: 'tensor',
})

```

--------------------------------

### Abort Active Operations with UpscalerJS

Source: https://upscalerjs.com/documentation/api/abort

Call this method to cancel any currently running asynchronous operations, such as model warm-up or image upscaling. Ensure an Upscaler instance is created before calling.

```javascript
const upscaler = new Upscaler();
upscaler.abort();
```

--------------------------------

### Create Tensor in Worker Thread

Source: https://upscalerjs.com/documentation/guides/browser/performance/webworker

Reconstruct a TensorFlow.js tensor from the received data and shape within the Web Worker. This tensor can then be used for upscaling.

```javascript
// Worker thread  
const tensor = tf.tensor(data, shape)  
```

--------------------------------

### Identify Graph Model JSON

Source: https://upscalerjs.com/documentation/troubleshooting

Inspect the model.json file to determine if it is a 'graph' model. This format is supported by Tensorflow.js.

```json
{"format": "graph-model",
```

--------------------------------

### Ensure Model Returns a Tensor

Source: https://upscalerjs.com/documentation/troubleshooting

UpscalerJS requires models to output tensors. If a custom model returns a non-tensor value, an 'Invalid Model Prediction' error will occur.

```javascript
Invalid Model Prediction
```

--------------------------------

### Identify Layers Model JSON

Source: https://upscalerjs.com/documentation/troubleshooting

Inspect the model.json file to determine if it is a 'layers' model. This format is supported by Tensorflow.js.

```json
{"format": "layers-model",
```

--------------------------------

### Ensure Model Returns Rank 4 Tensors

Source: https://upscalerjs.com/documentation/troubleshooting

UpscalerJS expects models to return rank 4 tensors representing image-like data. Custom models returning rank 3 tensors or non-image data will cause errors.

```javascript
Invalid Predicted Tensor
```

--------------------------------

### Unserialize Tensor in Cloudflare Worker

Source: https://upscalerjs.com/documentation/guides/other/cloudflare-worker

Unserialize the incoming JSON data into a TensorFlow.js tensor within the Cloudflare Worker.

```javascript
// cloudflare-worker script  
async function handleRequest(request) {
  const { data, shape } = await request.json()
  const tensor = tf.tensor(data, shape)
  ...

```
Tokens:
Raw