currust - a cursor converter

A tool written in Rust to convert cursor formats between Windows and Linux. Specifically, converting from the CUR/ANI format to the Xcursor format (plus some other features).

Installation

There are currently two supported methods of installation:

• download the binaries on the releases page (recommended)
• build from crates.io with cargo install currust

Usage (automatic)

The primary use-case of currust is to convert a Windows cursor theme to Linux. A cursor theme is a directory that contains some cursors, along with an installer file that uses either the INF or CRS format.

If the cursor theme being converted doesn't include an installer file, read the manual usage section.

A Windows cursor theme can be converted as such:

currust ./my-cursor-theme

This converts the theme and writes the produced X11 theme (which is a directory) in the current directory. Add the --out (or -o for short) argument to place it in the specified path.

currust ./my-cursor-theme -o ./please/go/here/instead

Cursor themes on Windows can be scaled by Windows itself. Unfortunately, this feature doesn't exist anywhere on Linux from what I know, so Xcursor themes have to include their own size variations if the provided sizes (usually just 32x32) is too small.

currust has support for both upscaling and downscaling cursors.

The --scale-to argument is used to specify what scale factors to scale to, along with --scale-with to specify a scaling algorithm to use (default: box).

Tip

The default algorithm (box) is meant for pixel-art. If you want smoother scaling, specify that with, e.g., Lanczos3 using --scale-with lanczos.

For example, to scale my-cursor-theme to 0.5x, 2x and 3x using Mitchell:

currust ./my-cursor-theme --scale-to 0.5 2 3 --scale-with mitchell

Note that this increases the size of the resulting cursor theme.

Usage (manual)

The cursor theme being converted may lack an installer file or have one in an unsupported format. To convert, pass the --manual flag, where a guided installation process will occur. Note that as of now, this configuration isn't saved--this must be done each time the theme is to be converted.

Manual conversion

A prompt will appear for each cursor in the theme that needs to be converted. A checkmark will appear on cursors you've already selected (though, you can re-select them if needed).

You can move up and down the list using the k and j keys respectively.

In case the (admittedly rudimentary) emoji/glyph visual representations of the cursor aren't enough, here's a convenient reference image you can use.

? Select the file representing 'Hand'.
Description: a hand pointing upwards
Used when: hovering over a link or anything that you can click
Names: link select, link
Looks like: 👆 or  ›
❯ 'Alternate Select.ani'
  'Busy.ani'
  'Diagonal Resize 1.ani'
  'Diagonal Resize 2.ani'
  'Handwriting.ani'
  'Help Select.ani'
  'Horizontal Resize.ani'
  'Link Select.ani'
  'Location Select.ani'
  'Move.ani'
  'Normal Select.ani' ✓
  'Person Select.ani'
  'Precision Select.ani'
  'Text Select 2.ani'
  'Text Select.ani'
  'Unavailable.ani'
  'Vertical Resize.ani'
  'Working In Background.ani'

Changing and installing the cursor theme

Afterwards, move the converted theme to the local ~/.icons. Any location specified in here should work.

Warning

Placing cursor themes in the system-wide /usr/share/icons isn't recommended due to the extra permissions required.

You can then set the converted theme as your cursor as such, depending on your DE:

• KDE: plasma-apply-cursortheme <theme_name> --size <size>
• GNOME: gsettings set org.gnome.desktop.interface cursor-theme <theme_name> && gsettings set org.gnome.desktop.interface cursor-size <size>
• Hyprland: hyprctl setcursor <theme_name> <size>

The theme name is the same as the name of the converted theme directory. If your DE isn't listed, look it up.

Example installation on KDE

❯ tree  # Expected cursor theme layout (as input)
.
└── [The Herta Cursor ver.2.0.0]
    ├── 01-Normal.ani
    ├── 02-Link.ani
    ├── 03-Loading.ani
    ├── 04-Help.ani
    ├── 05-Text Select Alt.ani
    ├── 05-Text Select.ani
    ├── 06-Handwriting.ani
    ├── 07-Precision.ani
    ├── 08-Unavailable.ani
    ├── 09-Location Select.ani
    ├── 10-Person Select.ani
    ├── 11-Vertical Resize.ani
    ├── 12-Horizontal Resize.ani
    ├── 13-Diagonal Resize 1.ani
    ├── 14-Diagonal Resize 2.ani
    ├── 15-Move.ani
    ├── 16-Alternate Select.ani
    ├── [Changelog].txt
    └── Installer.inf

2 directories, 19 files

❯ currust \[The\ Herta\ Cursor\ ver.2.0.0\] --scale-to 5 -o ~/.icons

❯ plasma-apply-cursortheme ~/.icons/The\ Herta\ Cursor\ ver\ 2.0.0 # If you're on KDE
Successfully applied the mouse cursor theme The Herta Cursor ver 2.0.0 to your current Plasma session

About Windows

For Windows, conversion still works. The only limitation is the creation of symlinks, which can be done through a created bash script once the converted theme is on a Linux system.

Note that the script (once on Linux) will need to be given execution permissions with chmod +x.

Goals

All the baseline goals I had for this project are complete, so this is closer to a "planned/future features" section. Note that not everything here may be added.

• Publish or otherwise for usage with cargo and package managers
• Replace bash script generation by exporting to tar.gz
• Conversion from Xcursor to ANI/CUR (i.e, the other way around)
• SVG cursor themes for KDE Plasma
• hyprcursor (cursor format for hyprland) support → covered by hyprcursor-util
• Have a guided installation process for themes with no installer file

---

The name ("currust") comes from a portmanteau of "cursor" and "Rust".

Any time I refer to "Linux", it may be better thought of as "Linux distributions" or "Xcursor".