Rusty Desktop Icons for Python

A Rust-powered desktop icon controller and GPU-backed animator, with Python bindings built using PyO3 and maturin. Inspect and restore desktop layouts, animate transitions, and apply built-in or custom shader effects.

Main GitHub repository | Documentation | Python guide | Report an issue

Features

• Enumerate desktop icons, positions, monitors, DPI and grid information.
• Move icons directly and read or change Windows desktop folder flags.
• Animate with configurable curves, independent axis motion and reversible timelines.
• Apply Glitch, Particle Vortex, Dust Transfer and Silk Flow effects, or trusted custom HLSL.
• Render scenes off-screen and export frames without moving real icons.

Showcases

These looping previews are off-screen renders over a desktop mockup, not screen recordings or FPS benchmarks. Click a preview to open its full-size version.

Movement	Glitch
Particle Vortex	Dust Transfer
Silk Flow

See the showcase export guide to render your own scenes.

Install (from PyPI)

Use CPython 3.9+ on Windows 10/11 x64 with a compatible wheel. Prebuilt wheels do not require Rust.

python -m pip install rusty-desktop-icons

Install (from source)

Install Rust 1.88+ and Visual Studio C++ Build Tools with the Windows SDK, then clone the repository:

git clone https://github.com/s0d3s/rusty-desktop-icons.git
cd rusty-desktop-icons
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install maturin==1.15.0
python scripts/generate-stubs.py
maturin develop --release -m crates/rdi-python/Cargo.toml

See the Python installation guide for build and troubleshooting details.

Example: Dust Transfer Round Trip

Turn two icons into drifting particles, swap their positions, then animate them home. Change DustTransfer to SilkFlow, ParticleVortex or Glitch to try another effect with its recommended movement and timing.

This changes your real desktop. Disable View > Auto arrange icons and start with a non-overlapping layout. The example selects the first two icons; use two on the same monitor, and do not rearrange icons or change display settings while it runs. Cleanup restores saved positions and the snap setting after normal completion or ordinary errors, but cannot survive force-killing the process.

from __future__ import annotations

import rusty_desktop_icons as rdi


def main() -> None:
  controller = rdi.DesktopController()
  original_flags = controller.get_flags()
  if original_flags & rdi.FolderFlag.FWF_AUTOARRANGE:
    raise RuntimeError("Disable desktop Auto arrange before running")
  icons = controller.list_icons()[:2]
  if len(icons) < 2:
    print("This example needs at least two desktop icons")
    return

  origins = [(icon.id, icon.position) for icon in icons]
  targets = [(icons[0].id, icons[1].position),
         (icons[1].id, icons[0].position)]
  name = rdi.BuiltinShader.DustTransfer
  preset = rdi.AnimationPreset.builtin(name)
  shader = rdi.Shader.compile(rdi.ShaderSource.builtin(name))
  effect = rdi.Effect(shader, envelope=preset.envelope)

  def play(positions: list[tuple[str, tuple[int, int]]]) -> None:
    specs = [
      rdi.IconAnimationSpec(
        icon_id, target, preset.duration, preset.movement, effect=effect
      )
      for icon_id, target in positions
    ]
    handle = controller.prepare(specs).start()
    try:
      reason = handle.wait()
      if reason.kind != rdi.FinishReasonKind.Completed:
        raise RuntimeError(str(reason))
      commit = handle.final_commit()
      if commit is not None and commit.missing_ids:
        raise RuntimeError(f"Unresolved icons: {commit.missing_ids}")
    finally:
      handle.stop()
      handle.wait()

  snap = rdi.FolderFlag.FWF_SNAPTOGRID
  try:
    controller.unset_flags(snap)
    play(targets)
    play(origins)
  finally:
    try:
      missing = controller.set_positions(origins)
      if missing:
        raise RuntimeError(f"Could not restore icons: {missing}")
    finally:
      controller.apply_flags(snap, original_flags)


if __name__ == "__main__":
  main()

Demo App

animate_timeline is a separate Rust terminal app for exploring animation without writing Python. Its Main, Curves and Shader Editor tabs provide reversible playback, timeline seeking, movement/envelope editing and built-in or custom HLSL shaders. It is not installed by pip.

Download animate_timeline.exe from the Assets section of the latest GitHub release. From PowerShell, in the download directory:

.\animate_timeline.exe --shader dust-transfer

Or build it with the Rust/Windows prerequisites listed above:

cargo install rusty-desktop-icons --bin animate_timeline
animate_timeline

Disable View > Auto arrange icons before launching. The demo moves real icons; press q to quit normally and restore their original positions. Avoid force-killing it. See the Demo App guide for controls, installation details and limitations.

Examples in this crate

• Smoke example — end-to-end sanity check.
• Function-sampled curves — demonstrates Curve.from_function with a damped-cosine curve.
• Motion-aware curves — demonstrates Curve.from_motion_function with a parametric gravity curve.

More recipes: layout and playback, timelines, and shaders.

Status and limitations

This is a proof of concept, with no stable API promise. Windows is the only working desktop backend; multi-monitor and mixed-DPI behavior remain work in progress. Thumbnail, shortcut-arrow and label rendering can differ from Explorer. Only one overlay session can run per process.

Use trusted shaders only. Custom HLSL is not sandboxed: expensive or malicious shaders can freeze the display or reset the GPU driver. Review third-party and AI-generated shader sources before compiling them.

Tests

.venv\Scripts\python.exe -m pytest crates\rdi-python\tests -v

License

Licensed under the Apache License 2.0. The license text is included in the distribution.