quicktex/docs/handbook/getting_started.md

Getting Started

Installation

Install and update using pip:

pip install -U quicktex

If you are on macOS, you need to install openMP to allow multithreading, since it does not ship with the built-in Clang. This can be done easily using homebrew. This is not required if building from source, but highly recommended.

brew install libomp

If you want, you can also install from source. First clone the git repo and install it with:

pip install .

and setuptools will take care of any dependencies for you.

The package also makes tests, stub generation, and docs available. To install the required dependencies for them, install with options like so:

pip install quicktex[tests,stubs,docs]

Usage

For detailed documentation on the {command}quicktex command and its subcommands see the {doc}commands.

Examples

Encoding a file

To encode a file in place, use the {command}encode command

quicktex encode auto bun.png # chooses format based on alpha
quicktex encode bc3 bun.png # encodes as bc3

the auto subcommand automatically chooses between bc1 and bc3 for your image depending on the contents of its alpha channel. Quicktex supports reading from all image formats supported by pillow.

By default, Quicktex converts in place, meaning the above command will produce a bun.dds file alongside the png. If you want to replace the png, use the -r flag to remove it after converting.

if you want to specify an output filename or directory use the -o flag.

quicktex encode auto -o rabbit.dds bun.png # produces rabbit.dds
quicktex.encode auto -o textures/ bun.png # produces textures/bun.dds, if textures/ exists

Encoding multiple files

quicktex is also able to convert multiple files at once, for example, to encode every png file in the images folder, use:

quicktex encode auto images/*.png # encodes in-place
quicktex encode auto -o textures/ images/*.png # encodes to the textures/ directory

please note that globbing is an operation performed by your shell and is not supported by the built in windows cmd.exe . If you are on Windows, please use Powershell or any posix-ish shell like fish.

Decoding files

decoding is performed exactly the same as encoding, except without having to specify a format. The output image format is set using the -x flag, and defaults to png. Quicktex supports writing to all image formats supported by pillow

quicktex decode bun.dds # produces bun.png
quicktex decode -x .tga bun2.dds # produces bun.tga