rclip 1.5.0

AI-Powered Command-Line Photo Search Tool

rclip - AI-Powered Command-Line Photo Search Tool

[Blog] [Demo on YouTube] [Paper]

rclip is a command-line photo search tool powered by the awesome OpenAI's CLIP neural network.

Installation

Linux

sudo snap install rclip

If your Linux distribution doesn't support snap, you can use one of the alternative installation options:

Prebuilt x86_64 binary

On Linux x86_64, you can install rclip as a self-containing binary.

1. Download the AppImage from the latest release.

2. Execute the following commands:

chmod +x <downloaded AppImage filename>
sudo mv <downloaded AppImage filename> /usr/local/bin/rclip

Using pip

pip install --extra-index-url https://download.pytorch.org/whl/cpu rclip

macOS

brew install yurijmikhalevich/tap/rclip

Alternative option:

Using pip

pip install rclip

Windows

pip install rclip

Usage

cd photos && rclip "search query"

When you run rclip for the first time in a particular directory, it's going to extract features from the photos, and this takes time. How long it takes depends on your CPU and the number of pictures you will search through. It took about a day to process 73 thousand photos on my NAS, which runs an old-ish Intel Celeron J3455.

For a detailed demonstration, watch the video: https://www.youtube.com/watch?v=tAJHXOkHidw.

Similar image search

You can use another image as a query by passing a file path or even an URL to the image file, and rclip will find the images most similar to the one you used as a query. If you are referencing a local image via a relative path, you must prefix it with ./. For example:

cd photos && rclip ./cat.jpg

# or use URL
cd photos && rclip https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/tests/e2e/images/cat.jpg

Check this video out for the image-to-image search demo: https://www.youtube.com/watch?v=1YQZKeCBxWM.

Combining multiple queries

You can add and subtract image and text queries from each other; here are a few usage examples:

cd photos && rclip horse + stripes
cd photos && rclip apple - fruit
cd photos && rclip "./new york city.jpg" + night
cd photos && rclip "2:golden retriever" + "./swimming pool.jpg"
cd photos && rclip "./racing car.jpg" - "2:sports car" + "2:snow"

If you want to see how these queries perform when executed on the 1.28 million images ImageNet-1k dataset, check out the demo on YouTube: https://www.youtube.com/watch?v=MsTgYdOpgcQ.

How do I preview the results?

The command from below will open top-5 results for "kitty" in your default image viewer:

rclip -f -t 5 kitty | xargs -d '\n' -n 1 xdg-open

I prefer to use feh's thumbnail mode to preview multiple results:

rclip -f -t 5 kitty | feh -f - -t

Help

rclip --help

Contributing

This repository follows the Conventional Commits standard.

Running locally from the source code

To run rclip locally from the source code, you must have Python and Poetry installed.

Then do:

# clone the source code repository
git clone [e-mail]:yurijmikhalevich/rclip.git

# install dependencies and rclip
cd rclip
poetry install

# activate the new poetry environment
poetry shell

If the poetry environment is active, you can use rclip locally, as described in the Usage section above.

Contributors ✨

Thanks go to these wonderful people (emoji key):

ramayer 💻

This project follows the all-contributors specification. Contributions of any kind are welcome!

License

MIT