MXTransform

MXTransform is a Rust program for doing matrix transformations on images.

See some example transformations here. 2D transformations are supported, which means you have to provide a 2x2 matrix.

Usage

Run mxtransform --help to see the detailed usage information.

In general, you need to provide an input image with -i or --input, a transformation matrix with -m or --matrix, and an output image with -o or --output.

Input format

• In case you need to provide a negative number as the first argument to an option, you can use = to indicate that the following arguments are not options. For example, to provide a negative X offset of -1920 you have to use: -f=-1920,0 or --offset=-1920,0. This is not required if the first argument is positive.

• Matrices are provided as comma-separated values. For example, the following matrix:

  | 1 2 |
  | 3 4 |
  

  Would be provided as -m 1,2,3,4 or --matrix 1,2,3,4. See above for how to provide negative numbers.

Examples

• To transform input.png to output.png using the following matrix, which will stretch the image horizontally by a factor of 2:

  | 2 0 |
  | 0 1 |
  

  You would run:

  mxtransform -i input.png -o output.png -m 2,0,0,1
  

• You can also specify an offset with -f or --offset followed by X,Y, in case the image ends up outside the bounds of the output image. For example to stretch the image horizontally by a factor of 2 and move the result 1920 pixels to the left:

  mxtransform -i input.png -o output.png -m 2,0,0,1 -f=-1920,0
  

Installation

Nix

1. Install Nix by following the instructions on the official website.

2. Get MXTransform from the flake in this repository (you might need to enable flake support):

   nix shell github:GGORG0/mxtransform
   

3. You can now run MXTransform from the shell:

   mxtransform --help
   

Cargo Binstall

Cargo Binstall downloads pre-built binaries from the GitHub releases page and installs them for you. You don't need to have Rust installed to use Cargo Binstall.

1. Install Cargo Binstall by following the instructions in the official repository. TL;DR:

   • Linux/MacOS

     curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
     

   • MacOS

     brew install cargo-binstall
     

   • Windows (in PowerShell)

     Set-ExecutionPolicy Unrestricted -Scope Process; iex (iwr "https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.ps1").Content
     

2. If you don't have Rust installed, make sure to add the Cargo bin directory to your PATH.

   The Binstall installer will tell you if you need to do this and conveniently print the path in question.

   • Linux/MacOS

     Temporarily:

     export PATH="$HOME/.cargo/bin:$PATH"
     

     Permanently:

     echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc if you use zsh (default on MacOS)
     
     # Then restart your shell or run
     source ~/.bashrc # or ~/.zshrc
     

   • Windows: You'll need to modify the PATH environment variable manually.

     1. Open the Start Search, type in "env", and choose "Edit the system environment variables".
     2. Click the "Environment Variables..." button.
     3. Under "System Variables", find the PATH variable and click "Edit...".
     4. Add the path to the Cargo bin directory (e.g. C:\Users\username\.cargo\bin - the path that was printed by the Binstall installer) to the list of paths.
     5. Click "OK" on all the windows to close them.
     6. You may need to restart your shell, log out and back in, or restart your computer for the changes to take effect.

3. Install MXTransform using Cargo Binstall:

   cargo-binstall mxtransform
   

4. You can now run MXTransform from anywhere in your shell:

   mxtransform --help
   

Getting the binary from the GitHub releases page

1. Go to the releases page.

2. Download the binary for your platform.

3. Extract the binary from the archive.

4. Open a shell in the directory where the binary is located.

5. Run the binary:

   • Linux/MacOS

     ./mxtransform --help
     

   • Windows

     mxtransform.exe --help
     

Cargo (compiling from crates.io)

1. Install Rust by using the official installer from rustup.rs.

2. Install MXTransform from crates.io using Cargo:

   cargo install mxtransform
   

3. You can now run MXTransform from anywhere in your shell:

   mxtransform --help