v1.0.0

v1.0.0

.github/workflows/publish.yml → .github/workflows/ci.yml

@@ -1,7 +1,7 @@
 # This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
 # For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
 
-name: publish
+name: ci
 
 on: push
 

README.md

@@ -1,65 +1,250 @@
-# splitea
+# SPLITEA
 
-[![build](https://github.com/crisconru/splitea/actions/workflows/publish.yml/badge.svg)](https://github.com/crisconru/splitea/actions/workflows/publish.yml)
+[![version](https://img.shields.io/npm/v/splitea)](https://www.npmjs.com/package/splitea) [![Bundle size minified](https://img.shields.io/bundlephobia/min/splitea/latest)](https://img.shields.io/bundlephobia/min/splitea/latest) [![build](https://github.com/crisconru/splitea/actions/workflows/publish.yml/badge.svg)](https://github.com/crisconru/splitea/actions/workflows/publish.yml)
 
-It is a tool to split images into tiles or pieces. The idea is based on the project [image-splitter](https://github.com/achimoraites/image-splitter).
+It is a tool to split images into pieces or tiles. Images can be splitted in three ways:
 
-It has just one entry point with three arguments and the response is an array of tiles:
+- Horizontal
+
+    ```typescript
+    import { horizontalTiles } from 'splitea'
 
-- `image`: The image to split. It is a string path or a buffer
-- `tiles`: All the information to create the tiles
-    - `mode`: How to cut the images
-    - `rows` / `height`: Number of rows to be cut or height in px of each tile
-    - `columns` / `width`: Number of columns to be cut or width in px of each tile
-    - `unique`: Options to specify if you just want tiles not repeated
-        - `distance`: Max distance between tiles to be filtered
-        - `difference`: Max difference between tiles to be filtered
-        - `requirement`: Condition to be filtered, one of them or both
-- `output`: Information for the created tiles
-    - `response`: Type of output, an array of Buffer (default) or the path of each tile
-    - `store`: Information if you want to store the tiles in the computer or not
-        - `path`: Where to store
-        - `name`: Filename pattern
-        - `extension`: Extension of the tiles
+    const tiles = await horizontalTiles(image, options)
+    ```
 
-For the tiles there are only these possible combinations:
+- Vertical
+
+    ```typescript
+    import { verticalTiles } from 'splitea'
 
-- `mode` = `"horizontal"` + (`columns` | `width`)
-- `mode` = `"vertical"` + (`rows` | `height`)
-- `mode` = `"grid"` + (`columns` + `rows` | `width` + `height`)
+    const tiles = await verticalTiles(image, options)
+    ```
 
-`columns` and `rows` are natural number while `width` and `height` are in pixels.
+- Grid
+
+    ```typescript
+    import { gridTiles } from 'splitea'
 
-For the output the default type is buffer and it is not stored. If you want to store the tiles in the computer you'll have to add store object.
+    const tiles = await gridTiles(image, options)
+    ```
 
-If you select response as `"path"` you have to add store object too.
+All the functions has two parameters:
+
+1. `image`: A `string` with the path of the image or a `Buffer` with the content of the image.
+2. `options`: An `object` 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
+
+```typescript
+import { horizontalTiles } from 'splitea'
+
+const numberOfColumns: number
+// ...
+const tiles = await horizontalTiles(image, { columns: numberOfColumns })
+```
+
+Get tiles by width
+
+```typescript
+import { horizontalTiles } from 'splitea'
+
+const tilesWidth: number
+// ...
+const tiles = await horizontalTiles(image, { width: tilesWidth })
+```
+
+Related to options
 
 ```typescript
-import { Splitea } from splitea
-
-type Image = string | Buffer
-
-type Tiles = {
-  mode: "horizontal" | "vertical" | "grid",
-  rows?: number,
-  columns?: number,
-  width?: number,
-  height?: number,
-  unique?: {
-    distance: number,
-    difference: number,
-    requirement: "one" | "both"
-  }
+interface HorizontalOptions extends Options {
+  columns?: number
+  width?: number
 }
+```
+
+## Vertical
 
-type Output = {
-  response: "buffer" | "path",
-  store?: {
-    path: string,
-    name: string,
-    extension?: "jpg" | "jpeg" | "png" | "bmp" | "gif" | "tiff"
-  }
+Image can be split by rows or height, but not both.
+
+Get tiles by rows
+
+```typescript
+import { verticalTiles } from 'splitea'
+
+const numberOfRows: number
+// ...
+const tiles = await verticalTiles(image, { rows: numberOfRows })
+```
+
+Get tiles by width
+
+```typescript
+import { verticalTiles } from 'splitea'
+
+const tilesHeight: number
+// ...
+const tiles = await verticalTiles(image, { height: tilesHeight })
+```
+
+Related to options
+
+```typescript
+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
+
+```typescript
+import { gridTiles } from 'splitea'
+
+const numberOfRows: number
+const numberOfColumns: number
+// ...
+const tiles = await gridTiles(image, { rows: numberOfRows, columns: numberOfColumns })
+```
+
+Get tiles by width & height
+
+```typescript
+import { gridTiles } from 'splitea'
+
+const tilesWidth: number
+const tilesHeight: number
+// ...
+const tiles = await gridTiles(image, { width: tilesWidth, height: tilesHeight })
+```
+
+Related to options
+
+```typescript
+interface GridOptions extends Options {
+  rows?: number
+  columns?: number
+  width?: number
+  height?: number
+}
+```
+
+## Options
+
+It is an object which gives you superpowers
+
+```typescript
+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:
+
+1. Response: What to return.
+2. Store Options: If you want to store the tiles in your computer.
+3. Unique Options: If you want all tiles or non repeated tiles.
+
+### Output Options
+
+```typescript
+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 is `Buffer[]`.
+- `response = 'file'` then the output is `string[]` 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
+
+```typescript
+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
+
+```typescript
+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 has `0.01` by default.
+- `difference`: It is a float number between 0 and 1. It has `0.01` by default.
+
+## Examples
+
+```typescript
+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' }
+)
 
-const tiles: Promise<Image[]> = await Splitea(image: Image, tiles: Tiles, output: Output)
 ```