npm package: @pixzle/cli
Description: CLI implementation of image fragmentation and restoration
Author: tuki0918
Latest version: 0.2.0

# @pixzle/cli

CLI implementation of image fragmentation and restoration using the `@pixzle/node` library.

## Installation

```bash
npm install @pixzle/cli
```

## Usage

### Shuffle

Fragments images into blocks and shuffles them.

```bash
pixzle shuffle <images...> -o <output_directory> [options]
```

| Option | Description | Required | Default |
|--------|-------------|:---------:|---------|
| `-o, --output <dir>` | Output directory (Required) | ✅ | - |
| `-b, --block-size <number>` | Pixel block size | ー | 8 |
| `-p, --prefix <prefix>` | Prefix for fragment files | ー | "img" |
| `-s, --seed <seed>` | Random seed (string) | ー | auto-generated 12-char ID |
| `--preserve-name` | Preserve original file names | ー | false |
| `--cross-image-shuffle` | Shuffle blocks across all images | ー | false |

**Example:**
```bash
pixzle shuffle input.png -o ./output
```

### Input multiple images

With `--cross-image-shuffle`, blocks are mixed across all input images, rather than being shuffled independently within each image.

| input 1 | input 2 | input 3 |
|:-------:|:---------------:|:---------------:|
| ![](../../.docs/input_sample.png) | ![](../../.docs/input_sample_mono.png) | ![](../../.docs/input_sample_blue.png) |

| output 1 | output 2 | output 3 |
|:-------:|:---------------:|:---------------:|
| ![](../../.docs/output_m0.png) | ![](../../.docs/output_m1.png) | ![](../../.docs/output_m2.png) |

> [!WARNING]
> - Currently, restoration with --cross-image-shuffle is only supported in Node.js and CLI environments.
> - May cause memory shortage depending on the number of images and block size.

----

### Restore

Restore fragmented images.

#### Using Manifest

```bash
pixzle restore <fragments...> -m <manifest_path> -o <output_directory>
```

| Option | Description | Required |
|--------|-------------|:----------:|
| `-m, --manifest <path>` | Path to manifest.json | ✅ |
| `-o, --output <dir>` | Output directory | ✅ |

**Example:**
```bash
pixzle restore ./output/*.png -m ./output/manifest.json -o ./restored
```

----

#### Manual Configuration (Single Image)

Restore a single image without a manifest file.

```bash
pixzle restore <fragment> -o <output_directory> -b <size> -s <seed> -w <width> -h <height>
```

| Option | Description | Required |
|--------|-------------|:----------:|
| `-o, --output <dir>` | Output directory | ✅ |
| `-b, --block-size <number>` | Pixel block size | ✅ |
| `-s, --seed <seed>` | Random seed (string) | ✅ |
| `-w, --width <number>` | Image width | ✅ |
| `-h, --height <number>` | Image height | ✅ |

**Example:**
```bash
pixzle restore ./fragmented.png -o ./restored -b 10 -s custom-seed -w 500 -h 500
```


## Manifest Structure

<details>
<summary>manifest.json</summary>

```json
{
  "id": "631631d5-bcaa-40ac-9c1e-efd6e89e4600",
  "version": "0.0.0",
  "timestamp": "2025-12-04T16:08:41.924Z",
  "config": {
    "blockSize": 8,
    "prefix": "img",
    "seed": "4f90d13aBc42",
    "preserveName": false,
    "crossImageShuffle": false
  },
  "images": [
    {
      "w": 500,
      "h": 500
    },
    {
      "w": 400,
      "h": 600
    },
    {
      "w": 600,
      "h": 400
    }
  ]
}
```
</details>