Skip to content

README.md

Latest commit

 

History

History
284 lines (203 loc) · 8.55 KB

README.md

File metadata and controls

284 lines (203 loc) · 8.55 KB

EN | CN | ID

Desktop Cat: QT Overlay 🐱

cat.gif

Python Versions PyPI Version Pepy Total Downloads

I made a cute little animated cat 🐈 for your desktop.
It's a lightweight Python + QT app — no borders, and you can drag it around easily.
Shows static first frame for 5 seconds, then plays GIF animation once, then loops back to static.
If you like it, maybe I'll share an AnimeGirl version next time~ 😉

image

1. Install Dependencies

Requirements: Python 3.9 or higher

sudo apt update
sudo apt install -y python3 python3-pip libxcb-cursor0
pip install PySide6 Pillow

2. Set up OpenAI API token 🔑

This application requires an OpenAI API token to access certain AI features.

Windows (PowerShell)

setx OPENAI_API_KEY "your_api_key_here"

Linux/macOS

export OPENAI_API_KEY="your_api_key_here"

After setting the token, restart your terminal or source your shell configuration to apply it.

3.1 Install from PyPI

# user install (recommended on Ubuntu)
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
python3 -m pip install mycat
# or system-wide (not recommended on Ubuntu desktop)
# sudo python3 -m pip install mycat
# Run
mycat
# or explicitly:
python3 -m mycat
# Upgrade
python3 -m pip install --upgrade mycat
# Uninstall
python3 -m pip uninstall mycat

3.2 Download from GitHub and install

# Install
git clone https://github.com/yumiaura/mycat
cd mycat
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
python3 -m pip install .
# Run
mycat
# Uninstall
python3 -m pip uninstall mycat

3.3 Run without installation 🏃‍♂️

# Clone repository
git clone https://github.com/yumiaura/mycat
cd mycat
python3 mycat/main.py --image images/cat.zip

4. Usage & Options 🎮

After installation, you can customize the cat 🐱 with various command-line options:

Basic Usage

# Run with default settings
mycat

# Run from source without installation
python3 mycat/main.py

Command-Line Options

--image, -i <path> 🖼️ Use a custom ZIP archive containing GIF animation instead of the default cat.

# Use your own cat ZIP archive
mycat --image ~/my-custom-cat.zip

# Example with full path
mycat --image images/cat.zip

ZIP Archive Requirements: 🐾

  • ZIP format containing exactly one GIF file
  • First frame of GIF is used as static image
  • GIF animation plays once, then returns to first frame
  • Images are automatically scaled if larger than 300x500 pixels

--pos <x> <y> 📍 Start the cat at a specific screen position (overrides saved position).

# Top-left corner
mycat --pos 0 0

# Center of 1920x1080 screen
mycat --pos 960 540

# Bottom-right area
mycat --pos 1600 900

Note: Position is saved automatically and restored on next launch.

Combined Examples 🎯

# Custom cat with specific wait time and position
mycat --image ~/my-cat.zip --wait 3 --pos 100 100

# Quick animation start in corner
mycat --image images/girl1.zip --wait 1 --pos 1500 800

# Slow animation start with custom ZIP
mycat --image /path/to/custom.zip --wait 10 --pos 0 0

Controls 🎮

  • Drag with left mouse button to move the cat 🐱
  • Right-click anywhere on the cat for context menu with image selection
  • Close via context menu or Ctrl+C in terminal

The cat remembers its position and selected image between sessions in ~/.config/pixelcat/config.ini.

4. Create animated GIF and ZIP archive 🎬

# Install ImageMagick for GIF creation
sudo apt install imagemagick

# Create animated GIF from sprite sheet
convert images/cat.png -crop 50%x100% +repage -set delay '200,100' -loop 0 images/cat.gif

# Create ZIP archive for the application
zip images/cat.zip images/cat.gif

5. Docker Usage 🐳

Run the desktop cat in a containerized environment for easy deployment across platforms. The Docker setup handles GUI forwarding to display the cat on your host desktop.

Prerequisites

  • Docker installed on your system
  • X server running on the host (Xorg on Linux, VcXsrv on Windows, XQuartz on macOS)

Linux 🐧

# Required before docker compose up (allow container access to X11)
xhost +local:docker

# Run the container
docker compose up --build

Windows 🪟

  1. Install an X server like VcXsrv
  2. Configure VcXsrv to allow connections from network clients
  3. Run the container:
docker compose -f docker-compose.windows.yml up

macOS 🍎

  1. Install XQuartz
  2. Allow connections from network clients in XQuartz preferences
  3. Run the container:
docker compose -f docker-compose.mac.yml up

How it Works

  • The container uses multi-platform Docker images compatible with Linux, Windows, and macOS hosts
  • GUI is forwarded from the container to the host's X server using TCP (Windows/macOS) or Unix socket (Linux)
  • X11 authorization is handled via mounted .Xauthority file
  • Host networking mode allows direct access to the host's display
  • The app runs with xcb platform plugin for native GUI performance

Customization

  • Modify docker-compose.yml files for different environments
  • Add custom ZIP archives by mounting volumes to /app/images/
  • Adjust display settings via environment variables

6. Troubleshooting 🔧

Common Issues

Cat doesn't appear or transparency doesn't work 🫥

  • On Linux, ensure you're using a compositing window manager (most modern desktop environments support this)
  • Try running with different window flags or check if your system supports ARGB visuals
  • For KDE Plasma, you may need to enable desktop effects

High CPU usage 💻

  • The animation runs at 60 FPS by default, which can be intensive on some systems
  • The CPU usage is usually minimal but depends on your system's Qt implementation

Window doesn't stay on top 📌

  • Some window managers or desktop environments may override the "always on top" setting
  • Try restarting your desktop session or check window manager settings

Custom image doesn't load ❌

  • Ensure your ZIP archive contains exactly one GIF file
  • Check that the GIF file is valid and not corrupted
  • Verify the file path is correct and the ZIP file exists
  • Make sure the GIF has proper frame delays for smooth animation

Position not saving 💾

  • Check that ~/.config/pixelcat/ directory exists and is writable
  • Look for error messages in the terminal when closing the application
  • The config file should be at ~/.config/pixelcat/config.ini

Installation issues on Windows 🪟

  • Ensure you have Python 3.9 or higher: python --version
  • Make sure you're using the run_windows.bat script from the project root
  • Check that PySide6 installed correctly: pip list | findstr PySide6
  • Try running python -c "import PySide6; print('PySide6 OK')" to test

Permission errors 🔒

  • On Linux, avoid using sudo for installation - use user installs instead
  • Check that virtual environment activation worked: which python3 and which pip

Python version issues 🐍

  • This application requires Python 3.9 or higher due to modern type hints
  • Check your version: python --version or python3 --version
  • If you have Python 3.8 or older, please upgrade to Python 3.9+
  • Tested and working on Python 3.9, 3.10, 3.11, and 3.12

Getting Help 🤝

  • Check the GitHub Issues for similar problems
  • Read CONTRIBUTING.md for development setup and guidelines
  • Create a new issue with your system details (OS, desktop environment, Python version)
  • Include any error messages from the terminal

License

MIT License

Thank you for reading to the end! 😸🐾