Package Exports

augment-image
augment-image/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (augment-image) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

augment-image

Image augmentation library and cli for machine learning tasks

Features

Rich combination of customizable image augmentation
- background color
- scale
- crop
- shear
- rotate
- gray-scale
- flipX
- flipY
- blur
Typescript support
Support usage from cli

Installation

npm install augment-image

You can also install augment-image with pnpm, yarn, or slnpm

Note that optional dependency should not be disabled, sharp installs the os-specific native package as optional dependencies.

Usage Example

Run the cli with npx:

npx augment-image [options]

Available options:

General:
  -h, --help                  Show this help message and exit.
  -v, --version               Show the version number and exit.

Configuration:
  -i, --init                  Initialize a configuration file.

Run Mode:
  -r, --run                   Run the main logic of the application.
  -s  --srcDir <path>         Specify the source directory. Default is "./images/raw".
  -o, --outDir <path>         Specify the output directory. Default is "./images/augments".
  -q, --quiet                 Disable verbose logging. By default, verbose is enabled.

Notes:

Use the --init option to generate a default config file.
You can edit the config in "config.json" in the current directory.
The config file must exist in the run mode.

Use as library:

import {
  aggressiveFilterGroupsOptions,
  buildFilterGroups,
  scanDirectory,
} from 'augment-image'

async function main() {
  // use custom settings
  let filterGroups = buildFilterGroups({
    // RGBA background will be used for out-of-range content when rotate, scale, or shear
    background: ['#ffffffff'],
    scale: [
      [0.5, 0.5],
      [1.0, 0.5],
      [2.0, 2.0],
    ],
    crop: [
      [Infinity, Infinity],
      [100, 100],
      [50, 50],
    ],
    shear: [
      [0, 0],
      [-8, 0],
      [+8, 0],
      [0, -8],
      [0, +8],
    ],
    rotate: [0, 8, -8, 16, -16],
    grayscale: 'both',
    flipX: true,
    blur: [0, 1, 2],
  })

  // use default settings
  filterGroups = buildFilterGroups(aggressiveFilterGroupsOptions)

  await scanDirectory({
    srcDir: './images/raw',
    outDir: './images/augmented',
    filterGroups,
    verbose: true,
  })
}
main().catch(e => console.error(e))

Typescript Signature

core functions and types

import { Sharp } from 'sharp'

/** @description the core function that apply all combination of image augmentation filters */
export function augmentImage(
  image: Sharp,
  filterGroups: FilterGroup[],
): AsyncGenerator<Sharp, void, unknown>

/** @description scan images in `srcDir` and save the augmented images in `outDir` */
export function scanDirectory(options: {
  srcDir: string
  outDir: string
  filterGroups: FilterGroup[]
  /** @description default `true` */
  verbose?: boolean
}): Promise<{
  fileCount: number
}>

/** @description generate filter groups with variants based on the given options */
export function buildFilterGroups(
  options: BuildFilterGroupsOptions,
): FilterGroup[]

export type BuildFilterGroupsOptions = {
  /**
   * @description for region that overflow when transform
   * default `['#00000000']`
   */
  background?: string[]
  /**
   * @description `Array<[w,h]>` in percentage, applied before crop
   * e.g. `[[0.8,1.2]]` for 80% in width and 120% in height
   * */
  scale?: [w: number, h: number][]
  /**
   * @description `Array<[w,h]>` in pixel unit, applied before after scale
   * e.g. `[[100,100],[100,150],[150,100]]`
   */
  crop?: [w: number, h: number][]
  /**
   * @description `Array<[x,y]>` in degree, applied after crop
   * e.g. `[[0,0],[-16,0],[+16,0],[0,-16],[0,+16]]`
   * */
  shear?: [x: number, y: number][]
  /**
   * @description in degree
   * e.g. `[-15, 0, 15]`
   * */
  rotate?: number[]
  grayscale?: 'always' | 'never' | 'both'
  flipX?: boolean
  flipY?: boolean
  /**
   * @description sigma range from 0 to 1000
   * e.g. `[0, 1]`
   * */
  blur?: number[]
}

/** @description a reference setting that balance the number of image augmentation combination and the time cost */
export let aggressiveFilterGroupsOptions: BuildFilterGroupsOptions

type FilterGroup = {
  name: string
  variants: Filter[]
}

type Filter = {
  (image: Sharp): Sharp[] | Sharp | Promise<Sharp[] | Sharp>
}

helper functions

import { Sharp } from 'sharp'

/** @description generate sequence of `number[]` */
export function range(args: {
  /** @description inclusive */
  from: number
  /** @description inclusive */
  to: number
  /** @description can be positive or negative */
  step: number
}): number[]

/** @description generate sequence of `number[]` */
export function rangeAround(args: {
  center: number
  /** @description inclusive */
  range: number
  /** @description can be positive or negative */
  step: number
}): number[]

/** @description generate `[[a,a],[b,b]]` into combination of `[[a,a],[a,b],[b,a],[b,b]]` */
export function expandCropSize(
  /** @description e.g. `[Infinity, 1000, 500, 300, 200, 100, 50]` */
  size: number[],
): number[][]

License

This project is licensed with BSD-2-Clause

This is free, libre, and open-source software. It comes down to four essential freedoms [ref]:

The freedom to run the program as you wish, for any purpose
The freedom to study how the program works, and change it so it does your computing as you wish
The freedom to redistribute copies so you can help others
The freedom to distribute copies of your modified versions to others