climax-rfglab 2025.10.6
climax is a Command Line IMAge eXplorer
Requires Python: >=3.10

![Logo](https://bitbucket.org/rfg_lab/climax/raw/0284bca63f357cddcf5c375eae0e2ad4863f9906/docs/climax_logo_full.jpg)
[![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)](https://opensource.org/licenses/GPL-3.0)

# [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) (a Command Line IMAge eXplorer)

## Installing [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/)

We recommend that you install [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) as a tool using [uv](https://github.com/astral-sh/uv):

    $ uv tool install climax-rfglab

or

    $ uvx --from climax-rfglab climax

A [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) executable will be created, which allows the tool to be run without uv. If the directory that contains the [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) executable is not in the PATH, a warning will be displayed and the following command can be issued to add it to the PATH:

    $ uv tool update-shell

[CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) can also be installed as a regular [Python](https://www.python.org/downloads/) package using [uv](https://github.com/astral-sh/uv):  

    $ uv pip install climax-rfglab

or [pip](https://pip.pypa.io/en):

    $ python3 -m pip install climax-rfglab

### A note on the Python interpreter

[CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) requires that you have [Python 3.10 or above](https://www.python.org/downloads/) installed.

### A note for developers

If you want to download the code and run from source, you will first need to compile the part of 
[CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) that uses [Rust](https://www.rust-lang.org/). The simplest way to do that is to install [maturin](https://github.com/PyO3/maturin) and run the following command within the [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) folder:

    $ maturin develop --release

After that, you can run [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) with:

    $ python -m climax.climax

## Using [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/)

After installing [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) with one of the methods above, You can invoke it with:

    $ climax <filename>

You can also run [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) without installing it, taking advantage of [uvx](https://github.com/astral-sh/uv):

    $ uvx --from climax-rfglab climax <filename>

There are a few ways to open an image with [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/):

- You can specifiy the path to the image that you want to open (e.g. *tests/fixtures/gray_stack.tif*) ... :

        $ climax tests/fixtures/gray_stack.tif

- ... including zarr images (e.g. *tests/fixtures/4D_stack.zarr*):

        $ climax tests/fixtures/4D_stack.zarr

- Or you can indicate a folder (*slices* in this example) that contains an image sequence:

        $ climax ./slices

- If there are image channels split into different files, you can specify a group of substrings to distinguish which files in the folder belong to which channel. For example, to open the files in the *slices* folder containing the substrings '488' and '561' as two different channels:

        $ climax ./slices -s 488 561

- You can use a list of paths to concatenate sideways (i.e. display side-by-side, but all the images must have the same dimensions!!):

        $ climax cells_movie_1.tif cells_movie_2.tif

- You can specify the color map used to display the image. The color map defaults to *'gray'*. Check [here](https://matplotlib.org/stable/tutorials/colors/colormaps.html) for a list of color maps.

        $ climax cells_movie.tif -c viridis

- Notice that if you try to open a color image, the channels will be displayed as different dimensions. Thus, for instance, if you open the [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) logo:

![Color](https://bytebucket.org/rfg_lab/climax/raw/3a3986cba576a7d879e9610794633b079b82e4f0/docs/color_image_display.gif)

- You can indicate the zoom factor initially used to display the image. Keep in mind that larger zoom values will take longer to render. The default value is 1.0, but you can select any of the values in **climax.zoom_factors** (currently 0.03125, 0.0625, 0.125, 0.25, 0.5, 1., 2., 4., 8., 16., and 32.):

        $ climax cells_movie.tif -z 2.0

The [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) dashboard provides tools to display and manipulate images:

|name|function|
|----------------------------------------|------------------------|
|rotate|rotate 90&deg; clockwise|
|flip h.|flip horizontally|
|flip v.|flip vertically|
|invert|invert color map|
|update|continuous/discrete update|
|x-y, z-y, z-x|slicing plane|
|auto|automated contrast adjustment (min-mode, max-99th percentile)|

The dashboard also shows the histogram of the image currently on display. The histogram is updated in real time as the user explores the image.

![Histogram](https://bytebucket.org/rfg_lab/climax/raw/e33bcebd015d502c6c425b254f941c334e2973f2/docs/climax_whistogram.gif)

A command bar provides additional functionality that can be invoked with the mouse or with several quick-keys:

|key|function|
|----------------------------------------|------------------------|
|.|next slice|
|,|previous slice|
|+|zoom in, uses nearest-neighbour or bilinear interpolation|
|-|zoom out, uses nearest-neighbour or bilinear interpolation|
|k|toggle dark mode on/off, initially off|
|o|open a new image|
|t|open an image sequence (select a folder)|
|i|toggle bilinear interpolation on/off, initially off (i.e. nearest neighbour interpolation)|


# [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) today

As we develop and improve [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/), there may be changes to the user interface. This is how [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/) looks as of today:

![CLIMAX today](https://bitbucket.org/rfg_lab/climax/raw/21dab008fe7286a7ceeac38af1c4c5002aca4fc8/docs/climax_today.gif)

## Citing [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/)
If you use [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/), please cite this repository. We are working on the paper!

## Sponsors

We are grateful for the generous support from the following agencies and institutions, which contribute to the
development and maintenance of [CLImax](https://bitbucket.org/rfg_lab/climax/src/master/):

![Sponsors](https://bitbucket.org/rfg_lab/climax/raw/0367742a0a3f4670b0d8299d52e0d52b6c8c601f/docs/sponsors.png)