diff --git a/docs/README.md b/docs/README.md index 4e004a5650393a112580ffacfa5c4789913e0c44..d9649a85688634036a27ceaff09425751a4192d0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,4 +2,51 @@ Crunch is an [open source](), GPL-3.0 licensed command line tool written in Rust for manipulating assets, designed to complement a game development asset pipeline. Commands can either be executed directly, or can -be executed via [pipeline files](). \ No newline at end of file +be executed via [pipeline files](). + +## Quick Installation + +If you're using Linux or Windows, you can download the pre-built binaries, copy them to your path and get going: + +- [Latest version for Windows](https://lab.lcr.gr/microhacks/crunch/-/jobs/artifacts/trunk/raw/target/x86_64-pc-windows-gnu/crunch.exe?job=build-windows) +- [Latest version for Linux](https://lab.lcr.gr/microhacks/crunch/-/jobs/artifacts/trunk/raw/target/release/crunch?job=build-linux) + +Check the [installation](getting_started/installation.md) page for more ways of sourcing your version of Crunch, including +installing from source on other platforms. + +## Basic Usage + +After you've installed the binary, you can use the `crunch` command to start manipulating assets. Check out the +help for a given command with `crunch <command> --help`, or by checking the link in the sidebar that correlates to the +command you want to run. + +```text +Usage: crunch <COMMAND> + +Commands: + rotate Rotate an image clockwise by the given degree + extrude Take each tile in an image and expand its borders by a given amount. Optionally fill with nearby pixels instead of empty space + palette Create a palette file containing every distinct colour from the input image + scale Resize an image by a scale factor + flip Flip an image along one or more axis + remap Convert the colour space of an image to that of a given palette file + pipeline Execute a predefined pipeline + reduce Limit the number of colours by quantity or threshold + split Take a spritesheet and split into individual sprites, skipping empty space + help Print this message or the help of the given subcommand(s) + +Options: + -h, --help Print help + -V, --version Print version +``` + +### Updating from 0.4 to 0.5 + +`0.5.0` contains a breaking change to the argument order for commands. From `0.5` onwards, the command being +executed is now specified **before** the input and output file paths. This is because some commands don't use +both an input and an output, causing version `0.4` and lower to require a dummy value in those locations. + +For Example: + +- **0.4**: `crunch ./myimage.png ./myimage-flipped.png flip -d both` +- **0.5**: `crunch flip -d both ./myimage.png ./myimage-flipped.png` diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index ebf99746043fc85a82cb2e6066b343a82d330b97..9bacf58cc49651c8e7cad27259802b66752c91e9 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -19,3 +19,6 @@ * [pipeline](commands/pipeline.md) ### Pipelines +* +* [Overview](pipelines/getting_started.md) +* [pipeline.toml Format](pipelines/file_format.md) diff --git a/docs/commands/extrude.md b/docs/commands/extrude.md index 14b534df787da7b52858741b473e2e874b237674..6636d1fdcb1f1a48bcfd532c102f0dfb2c9b8aaf 100644 --- a/docs/commands/extrude.md +++ b/docs/commands/extrude.md @@ -1,3 +1,28 @@ # Command: Extrude -## Usage \ No newline at end of file + +Adds padding to a spritesheet and spacing to the sprites within that sheet. Extruding a spritesheet is +useful for getting rid of stray pixels being rendered from neighbouring tiles due to floating point +issues in your rendering shaders. + +## Usage + +```text +Usage: crunch extrude [OPTIONS] <INPUT> <OUTPUT> + +Arguments: + <INPUT> The path to the spritesheet file + <OUTPUT> The path to write the extruded spritesheet + +Options: + -x, --space-x <SPACE_X> The amount of horizontal space to add between each sprite in the image [default: 0] + -y, --space-y <SPACE_Y> The amount of vertical space to add between each sprite in the image [default: 0] + -p, --padding <PADDING> The amount of padding to add around the edge of the spritesheet [default: 0] + -t, --tile-size <TILE_SIZE> The size of each tile in the spritesheet. Assumed to be square tiles [default: 32] + -h, --help Print help + -V, --version Print version +``` + +## Example + + \ No newline at end of file diff --git a/docs/commands/flip.md b/docs/commands/flip.md index f4199f17fed49afd87caf2c4bde0273675ff22a6..a53c23b9817f8fcb08d890d471d8669b7b73b7e6 100644 --- a/docs/commands/flip.md +++ b/docs/commands/flip.md @@ -1,5 +1,26 @@ # Command: Flip +Take the input image and invert it along one or both of the horizontal and vertical planes. + ## Usage -`crunch flip -d vertical ./myimage.png ./myimage-flipped.png` \ No newline at end of file +```text +Usage: crunch flip --direction <DIRECTION> <INPUT> <OUTPUT> + +Arguments: + <INPUT> The path to the image file + <OUTPUT> The path to write the flipped image + +Options: + --direction <DIRECTION> The axis along which the image should be flipped [possible values: vertical, horizontal, both] + -h, --help Print help + -V, --version Print version +``` + +## Arguments + +- `direction`: Must be specified. Defines which axes should be flipped - refer to the example below for a visual representation + +## Example + + \ No newline at end of file diff --git a/docs/commands/palette.md b/docs/commands/palette.md index 88c1e4a5d7cf159d8fd7a14d594c955b94123638..41035da3320aa366546732713a90ca75ae2d6295 100644 --- a/docs/commands/palette.md +++ b/docs/commands/palette.md @@ -1,3 +1,24 @@ # Command: Palette -## Usage \ No newline at end of file +Extract a palette from a given image. The palette is saved in either image format (one colour = 1 pixel), common +for sites like https://lospec.com, or in a text format, where each line of the file contains one hex encoded +RGBA colour (8 hex digits + leading hash) + +## Usage + +```text +Usage: crunch palette [OPTIONS] <INPUT> <OUTPUT> + +Arguments: + <INPUT> The path to the image file + <OUTPUT> The path to write the palette data + +Options: + -f, --format <FORMAT> The format for the palette file. PNG will output an image with colours, while TXT will output a text file with one hex value per line [default: png] [possible values: txt, png] + -h, --help Print help + -V, --version Print version +``` + +## Example + + \ No newline at end of file diff --git a/docs/commands/remap.md b/docs/commands/remap.md index acf544b03beb7af585d774deba51420c91967898..89a4e0839d5b5b51141ac3bb85418ad78d5c5abc 100644 --- a/docs/commands/remap.md +++ b/docs/commands/remap.md @@ -1,3 +1,24 @@ # Command: Remap -## Usage \ No newline at end of file +Given an input image and an input palette, create an output image where every colour in the input image is +mapped to the closest matching colour in the input palette. Closeness is determined by using the Delta-E 2000 +colour similarity of each colour + +## Usage + +```text +Usage: crunch remap --palette <PALETTE> <INPUT> <OUTPUT> + +Arguments: + <INPUT> The path to the image file + <OUTPUT> The path to write the recoloured image + +Options: + -p, --palette <PALETTE> The path to the palette file containing the output colours + -h, --help Print help + -V, --version Print version +``` + +## Example + + \ No newline at end of file diff --git a/docs/commands/rotate.md b/docs/commands/rotate.md index 13b7f2ae79a8dfffdabed6b24d429b81dedc64bd..8ed350a5f56e02dad8d1ce635c653b6a39c98374 100644 --- a/docs/commands/rotate.md +++ b/docs/commands/rotate.md @@ -1,3 +1,30 @@ # Command: Rotate -## Usage \ No newline at end of file +Take the input image and apply a number of 90 degree rotation steps to it. Does not support arbitrary rotations. + +## Usage + +```text +Usage: crunch rotate --amount <AMOUNT> <INPUT> <OUTPUT> + +Arguments: + <INPUT> The path to the spritesheet file + <OUTPUT> The path to write the extruded spritesheet + +Options: + -a, --amount <AMOUNT> How many 90 degree steps should this image be rotated by [possible values: one, two, three] + -h, --help Print help + -V, --version Print version +``` + +## Arguments + +- `amount`: Must be specified. Defines how many steps should be applied to this image. Steps are clockwise, three +clockwise steps are equivalent to one counter-clockwise steps. Values: + - `one`: 90 degrees + - `two`: 180 degrees + - `three`: 270 degrees + +## Example + + \ No newline at end of file diff --git a/docs/commands/scale.md b/docs/commands/scale.md index de6231bafa970a50a479e5175ddca3fe9ea7b303..02e7071a846e7cc856209708e6ebbae4aee05e94 100644 --- a/docs/commands/scale.md +++ b/docs/commands/scale.md @@ -1,3 +1,27 @@ # Command: Scale +Apply a percentage multiplier to the size of the input image. To nicely scale pixel art, it is recommended +to use a power of 2 as your scale (e.g. 2.0, 4.0, 8.0) -## Usage \ No newline at end of file +## Usage + +```text +Usage: crunch scale [OPTIONS] <INPUT> <OUTPUT> + +Arguments: + <INPUT> The path to the image file + <OUTPUT> The path to write the scaled image + +Options: + --factor <FACTOR> The scale factor to use; numbers between 0-1 shrink the image; numbers > 1 enlarge [default: 1] + -h, --help Print help + -V, --version Print version +``` + +## Arguments + +- `factor`: Must be specified. Defines how many steps should be applied to this image. Steps are clockwise, three + clockwise steps are equivalent to one counter-clockwise steps. Values: + +## Example + + \ No newline at end of file diff --git a/docs/commands/split.md b/docs/commands/split.md index bfbfaf24c23cc4691725225b1a10c4186a193633..2b8bf0053cbde5ed2479dbe8e9a4143265866f7d 100644 --- a/docs/commands/split.md +++ b/docs/commands/split.md @@ -1,3 +1,35 @@ # Command: Split -## Usage \ No newline at end of file +Convert one image file into multiple image files. By default, the output file names will be equal to the +given tile's GID. This can instead be set to "sequential", whereby the file names will use consecutive +numbering from 0 to the total number of files that have been output. + +The difference between the two naming schemes is based on crunch not outputting empty images. +The default GID based file names are stable, assuming the number of rows or columns in an image remains +the same, and will correlate to the IDs used by popular tilemap editors. On the other hand, Sequential +mode does not factor in empty tiles - this means that if a previously empty tile has content added to it, +subsequent tiles will be output with a different file name (e.g. 1 additional tile would increment numeric +file names by 1 for every tile after). + +## Usage + +```text +Usage: crunch split [OPTIONS] <INPUT> <OUTPUT> + +Arguments: + <INPUT> The path to the spritesheet file + <OUTPUT> The base path for all of the created sprites. Should be a directory, which will be created if it does not exist + +Options: + -x, --space-x <SPACE_X> The amount of horizontal space between each sprite in the image [default: 0] + -y, --space-y <SPACE_Y> The amount of vertical space between each sprite in the image [default: 0] + -p, --padding <PADDING> The amount of space around the edge of the image [default: 0] + -t, --tile-size <TILE_SIZE> The size of each tile in the spritesheet. Assumed to be square tiles [default: 32] + -s, --sequential When set, files will be numbered consecutively, regardless of empty sprites. By default, files will be numbered based on their inferred "tile id", based on position in the sheet + -h, --help Print help + -V, --version Print version +``` + +## Example + + \ No newline at end of file diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md index 38cb62dc337c31463fc45878de5c734cd779aa7f..89f938d22b7e5d0701a4491fcfebaaba3e69e23e 100644 --- a/docs/getting_started/installation.md +++ b/docs/getting_started/installation.md @@ -1,18 +1,29 @@ # Installation -There are a few ways you can install Crunch, depending on your needs +There are a few ways you can install Crunch, depending on your needs. Pre-compiled nightly builds are provided +for Windows and Linux, but the tool can be compiled for other platforms using other install methods ## Pre-built Binaries -- [Latest version for Windows]() -- [Latest version for Linux]() +Crunch is automatically built for Windows and Linux when changes are merged to the tracking branch, pass +tests, and compiles successfully. These binaries contain the latest updates, and may differ slightly from +these docs: + +- [Latest version for Windows](https://lab.lcr.gr/microhacks/crunch/-/jobs/artifacts/trunk/raw/target/x86_64-pc-windows-gnu/crunch.exe?job=build-windows) +- [Latest version for Linux](https://lab.lcr.gr/microhacks/crunch/-/jobs/artifacts/trunk/raw/target/release/crunch?job=build-linux) ## Via Cargo -`cargo install crunch` +To install via Cargo, you will need a stable rust toolchain installed. You can install one with [Rustup](https://rustup.rs/). +Installation using this method will install the latest stable published version, which will correlate with these docs. + +`cargo install crunch-cli` ## From Source +You can get a copy of the GPL-3.0 licensed Crunch source code from [Microhacks Labs](https://lab.lcr.gr/microhacks/crunch), +and compile it yourself. As with the Cargo installation method, you will need a stable rust toolchain. + ```bash git clone https://lab.lcr.gr/microhacks/crunch.git crunch cd crunch diff --git a/docs/images/Extrude.png b/docs/images/Extrude.png new file mode 100644 index 0000000000000000000000000000000000000000..7e1727a4edba2e73aec7257d7a42b01d147b595d Binary files /dev/null and b/docs/images/Extrude.png differ diff --git a/docs/images/Flips.png b/docs/images/Flips.png new file mode 100644 index 0000000000000000000000000000000000000000..43d566d715d89a2ce0806179e65a365d2019e1b7 Binary files /dev/null and b/docs/images/Flips.png differ diff --git a/docs/images/Palette.png b/docs/images/Palette.png new file mode 100644 index 0000000000000000000000000000000000000000..8a9d3b20a914eae31fc640473df37c3db8437d3d Binary files /dev/null and b/docs/images/Palette.png differ diff --git a/docs/images/Remap.png b/docs/images/Remap.png new file mode 100644 index 0000000000000000000000000000000000000000..5f4851cd17db8743dc34b1e54004f218d1ab8e86 Binary files /dev/null and b/docs/images/Remap.png differ diff --git a/docs/images/Rotation.png b/docs/images/Rotation.png new file mode 100644 index 0000000000000000000000000000000000000000..41d16f97212375ce9660921e1d79eedaf3dded00 Binary files /dev/null and b/docs/images/Rotation.png differ diff --git a/docs/images/Scale.png b/docs/images/Scale.png new file mode 100644 index 0000000000000000000000000000000000000000..c57a2162f2ed9db37e30e92eb0d2f6da6199bc27 Binary files /dev/null and b/docs/images/Scale.png differ diff --git a/docs/images/Split.png b/docs/images/Split.png new file mode 100644 index 0000000000000000000000000000000000000000..2293fd0716692fd37d455c2a238302e93cf0e1de Binary files /dev/null and b/docs/images/Split.png differ diff --git a/docs/pipelines/file_format.md b/docs/pipelines/file_format.md new file mode 100644 index 0000000000000000000000000000000000000000..9a399e9028ad5ddb019d2d5678fe4fb2fe3e7023 --- /dev/null +++ b/docs/pipelines/file_format.md @@ -0,0 +1,3 @@ +# Pipeline.toml +## _WIP_ + diff --git a/docs/pipelines/getting_started.md b/docs/pipelines/getting_started.md new file mode 100644 index 0000000000000000000000000000000000000000..47af354f9ed1808d3c89527ea88df96b15cd6ba7 --- /dev/null +++ b/docs/pipelines/getting_started.md @@ -0,0 +1,6 @@ +# Getting Started With Pipelines +## _WIP_ + +### Execution Model + +### Data Flow \ No newline at end of file