splitea
v1.0.0
Published
Splitea is a utility to split images in different sizes
Downloads
17
Readme
SPLITEA
It is a tool to split images into pieces or tiles. Images can be splitted in three ways:
Horizontal
import { horizontalTiles } from 'splitea' const tiles = await horizontalTiles(image, options)
Vertical
import { verticalTiles } from 'splitea' const tiles = await verticalTiles(image, options)
Grid
import { gridTiles } from 'splitea' const tiles = await gridTiles(image, options)
All the functions has two parameters:
image
: Astring
with the path of the image or aBuffer
with the content of the image.options
: Anobject
with all the options available.
Below there are sections related to each split mode in a simple way.
If you want to know more details about options
go to the last section.
Horizontal
Image can be split by columns or width, but not both.
Get tiles by columns
import { horizontalTiles } from 'splitea'
const numberOfColumns: number
// ...
const tiles = await horizontalTiles(image, { columns: numberOfColumns })
Get tiles by width
import { horizontalTiles } from 'splitea'
const tilesWidth: number
// ...
const tiles = await horizontalTiles(image, { width: tilesWidth })
Related to options
interface HorizontalOptions extends Options {
columns?: number
width?: number
}
Vertical
Image can be split by rows or height, but not both.
Get tiles by rows
import { verticalTiles } from 'splitea'
const numberOfRows: number
// ...
const tiles = await verticalTiles(image, { rows: numberOfRows })
Get tiles by width
import { verticalTiles } from 'splitea'
const tilesHeight: number
// ...
const tiles = await verticalTiles(image, { height: tilesHeight })
Related to options
interface VerticalOptions extends Options {
rows?: number
height?: number
}
Grid
Image can be split by rows & columns or width & height, but not both.
Get tiles by rows & columns
import { gridTiles } from 'splitea'
const numberOfRows: number
const numberOfColumns: number
// ...
const tiles = await gridTiles(image, { rows: numberOfRows, columns: numberOfColumns })
Get tiles by width & height
import { gridTiles } from 'splitea'
const tilesWidth: number
const tilesHeight: number
// ...
const tiles = await gridTiles(image, { width: tilesWidth, height: tilesHeight })
Related to options
interface GridOptions extends Options {
rows?: number
columns?: number
width?: number
height?: number
}
Options
It is an object which gives you superpowers
interface Options {
// Output Options
response: 'buffer' | 'file' // 'buffer' by default
// Store options
path?: string
filename?: string
extension?: 'png' | 'jpg' | 'jpeg' | 'giff' | 'tiff'
// Unique options
unique?: boolean // false by default
uniqueRequirement: 'all' | 'distance' | 'difference' // 'all' by default
distance?: number // Float between 0 - 1
difference?: number // Float between 0 - 1
}
It can be divided in 3 cathegories:
- Response: What to return.
- Store Options: If you want to store the tiles in your computer.
- Unique Options: If you want all tiles or non repeated tiles.
Output Options
interface Options {
response: 'buffer' | 'file' // 'buffer' by default
}
The output is an array, Buffer[]
or string[]
.
The property for that is response
. It can have just two values: 'buffer'
or 'file'
.
response = 'buffer'
then the output isBuffer[]
.response = 'file'
then the output isstring[]
where each element is the absolute path to each tile.
If response = 'file'
then splitea needs to store in disk, so this implies to enter
at path
property of the Store Options (check in the next section).
Store Options
interface Options {
path?: string
filename?: string
extension?: 'png' | 'jpg' | 'jpeg' | 'giff' | 'tiff'
}
Splitea can store in disk all the tiles. If the output are the images in disk (response = 'file'
), at least path
is mandatory.
path
: Absolute path where tiles must be stored.filename
: The main name of each tile. If none is provided, it has the value'tile'
.extension
: Image extension for all tiles. If none is provided, it has the value of the image extension.
Unique Options
interface Options {
unique?: boolean // false by default
uniqueRequirement: 'all' | 'distance' | 'difference' // 'all' by default
distance?: number // Float between 0 - 1, 0.01 by default
difference?: number // Float between 0 - 1, 0.01 by default
}
Splitea give you all the tiles by default. But it can give you only the non repeated tiles too.
To get that unique = false
.
To check if the images are non repeated it uses two concepts:
Distance means the Hamming distance of the pHash (percentual Hash algorithm).
Difference means the difference between pixels using PixelMatch.
unique
: By default to false, if you need non repeated it needs to be true.uniqueRequirement
: By default is'all'
, which means to use distance and difference. If you only want to use one of them, the value should be'distance'
or'difference'
.distance
: It is a float number between 0 and 1. It has0.01
by default.difference
: It is a float number between 0 and 1. It has0.01
by default.
Examples
import { horizontalTiles, VerticalTiles, gridTiles } from 'splitea'
// ...
import fs from 'node:fs'
const imagePath = '/path/to/my/image'
const imageBuffer = fs.readFileSync(imagePath)
// ...
// Horizontal Tiles: 4 tiles
const horizontal = horizontalTiles(imagePath, { columns: 4 })
// Vertical Tiles: 5 tiles non-repeated
const vertical = verticalTiles(imageBuffer, { rows: 4, unique: true })
// Grid Tiles: Tiles of 40 x 60 px and stored in disk
const gridNoUniqueBuffer = gridTiles(
imagePath,
{ width: 40, height: 60, path: '/store/path/grid', img: 'images' }
)
const gridUniqueImagesPath = gridTiles(
imageBuffer,
{ width: 40, height: 60 , response: 'file', path: '/store/path/gridUnique', img: 'gridtiles' }
)