Giter VIP home page Giter VIP logo

rclip's Introduction

rclip - AI-Powered Command-Line Photo Search Tool

All Contributors

[Blog] [Demo on YouTube] [Paper]

rclip logo

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

Installation

Linux

sudo snap install rclip
Alternative options (AppImage and pip)

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

AppImage (self-contained x86_64 executable)

On Linux x86_64, you can install rclip as a self-contained executable.

  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 (pip)
pip install rclip

Windows

  1. Download the "*.msi" from the latest release.
  2. Install rclip by running the installer.
Alternative option (pip)
pip install rclip

Usage

cd photos && rclip "search query"

rclip usage demo

When you run rclip for the first time in a particular directory, it will extract features from the photos, which takes time. How long it will take 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, 7 minutes to index 50 thousand images on my MacBook with an M1 Max CPU, and three hours to process 1.28 million images on the same MacBook.

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?

If you are using either one of iTerm2, Konsole (version 22.04 and higher), wezterm, Mintty, or mlterm all you need to do is pass --preview (or -p) argument to rclip:

rclip -p kitty
Using a different terminal or viewer

If you are using any other terminal or want to view the results in your viewer of choice, you can pass the output of rclip to it. For example, on Linux, 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

The -f param or --filepath-only makes rclip print the file paths only, without scores or the header, which makes it ideal to use together with a custom viewer as in the example.

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 [email protected]: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 and organizations (emoji key):

ramayer
ramayer

💻
Caphyon
Caphyon

🚇

Thanks to Caphyon and Advanced Installer team for generously supplying rclip project with the Professional Advanced Installer license for creating the Windows installer.

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

License

MIT

rclip's People

Contributors

allcontributors[bot] avatar ramayer avatar yurijmikhalevich avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

rclip's Issues

feat: search text in images

I tested that searching text in images. It works, though not so good. Any idea to improve the performance of searching text in images? Thank you.

feat: add an option to store rclip DB alongside of the indexed images

Hello!

I have noticed that rclip saves the database based on an environment variable or a system data directory:

def get_app_datadir() -> pathlib.Path:

Is there any reason why we can't configure rclip to save the database on the current directory ala git? If I am not mistaken, that would allow users to move/copy these folders and keep a database of the cached images. This would be really useful if someone managed their albums through a cloud platform, allowing them to also upload the database file and share it across devices.

perf: speed up the execution

I'm getting 3.7 seconds average execution time on my laptop (i7-7700HQ) when searching through 73 thousand images, where:

0.85s is "import clip"
1.75s is model loading
0.47s is querying the data from the SQLite DB
0.26s is actual querying

On my NAS (Intel Celeron J3455), it executes in 7.8s average, where:
1.73s "import clip"
3.22s model loading
1.87s getting features
0.8s search

~65% of the execution time is the CLIP model loading, so reducing this time can be the vector worth exploring first.

One of the options to take is to make rclip a daemon that has the model loaded all the time and query it, but this results in the extra RAM consumption of a few hundred megabytes, and, given that querying is a relatively rare operation, I don't like it.

Another option is to convert the CLIP model to Tensorflow Lite. It can be tricky but should reduce both the RAM consumption and the execution time, so it may be worth exploring.

feat: add a mode in which it will populate the indexed images' EXIF data with tags

UPD: this feature is being worked on and will be released as a separate tool, rtag. You can follow the development by starring and watching the rtag repository. This Issue will be closed once rtag v1 is released.

Tags should be taken from a fixed, pre-defined set. The ImageNet competition tag list is a good place to start, wikientities is another one.

The v1 of the feature should look like this from the user perspective:

$ rclip tag
This operation will overwrite the tags stored in your images' EXIF metadata. This will change the image files and will make you loose any existing keywords stored on your images.
Proceed? y/n y
/photos [#####]

For v1, it should write the tags from the list of the ImageNet-1k tags, based on a certain threshold (should be determined empirically).

Interested user: https://www.youtube.com/watch?v=MsTgYdOpgcQ&lc=Ugzl8qVAiVsek_2TwoZ4AaABAg

bug: error on redirecting output on unicode file paths

when there are unicode file names, rclip runs well only in the console window. However, if you redirect the output to file, pipe, etc. it will throw errors. This blocks me from integrating rclip into my app.

See below screenshot:

  • 1st run: [OK] console output
  • 2nd run: [FAILED] redirecting output
image

feat: allow "negative" text queries

A good example of what I mean is http://image-search.0ape.com/search?q=naked%20-person.

Thanks, @ramayer for the rclip-server and the inspiration!

Requirements:

  • the current interface rclip "query" should continue to work
  • it should correctly support following examples:
    rclip "multi word query -word1 -word2"
    rclip "query -'multi word negative'"
    rclip 'query -"multi word negative"' (i.e., it should work with any type of quotes)

rclip "multi word query -word2 some other words" should error with the suggestion to use quotes around the negative since it's unclear how to parse it

feat: improve indexing output

Ensure that instead of multiple progress bars, rclip displays a single progress bar which will include the total number of files as soon as possible

no results on fresh pip install

pip version 23.2.1

$ pip install rclip
$ rclip cat
---
checking images in the current directory for changes; use "--no-indexing" to skip this if no images were added, changed, or removed
0images [00:00, ?images/s]

100%|███████████████████████████████████████| 354M/354M [00:41<00:00, 8.58MiB/s]
score	filepath

No results.

feat: allow searching for similar images by providing a path or URL to an image

Sometimes it's more convenient to search for "a picture similar to the one I have in mind", instead of trying to describe it with words. Especially considering the extremely short phrases CLIP allows.

I'd like to be able to run:

 rclip https://i.redd.it/a7jf5rlghsz51.jpg

to return pictures of similar buildings like these.

It would also be nice to be able to search for pictures similar to a local file, like rclip /tmp/turtle.jpg and/or rclip file:///tmp/turtle.jpg.

This branch has a working work-in-progress for both of those features; but probably isn't ready for a pull request yet because it has a python3.9 dependency (str.removeprefix is a 3.9 feature). If you're interested, I'll remove that dependency and open a pull request.

feat: add support for Sixel and kitty graphics protocols for image preview

This is a low priority because we already support the iTerm Inline Graphics protocol, which allows you to preview images in iTerm2, Konsole 22.04+, wezterm, Mintty, and mlterm.

Vote and comment on this issue if you want to prioritize implementing the support for Sixel and kitty protocols. And, if you feel like it, give a stab at it yourself and submit the PR. Contributors are welcome! :)

FasterViT?

In the recent ML news, I noticed mentions of FasterViT, a new model with some architecture changes that is said to outperform others in the performance to accuracy ratio. I immediately wondered if it can give tools like this any performance gain.

https://github.com/NVlabs/FasterViT

Any idea the feasibility of adding an exclude or ignore directory option?

E.g., like rsync has the --exclude=PATTERN that can be repeated...

I see this in main.py:

EXCLUDE_DIRS = ['@eaDir', 'node_modules', '.git']
EXCLUDE_DIR_REGEX = re.compile(r'^.+\/(' + '|'.join(re.escape(dir) for dir in EXCLUDE_DIRS) + r')(\/.+)?$')

Do you have any interest in having additional exclude directories specified as command line arguments? Or perhaps an e.g. .rclipskip, .rclipexclude, .rclipignore file that contains directory patterns?

feat: add optional non-breaking `ViT-L/14@336px` support

For those who wants extra preciseness and ready to sacrifice speed for them:

Stats from a dataset of 269 photos on a much slower NAS (using the v1.2.3 and v2.0.0-pre AppImage distributions):

  • ingestion: 3m56.626s vs 125m0.507s (+3070%)
  • search: 0m18.064s vs 3m19.742s (+1006%)

More details are here.

Like and comment if you want to see the largest CLIP model in rclip.

Import error on fresh homebrew install

Homebrew 4.2.12

$ brew install yurijmikhalevich/tap/rclip
$ rclip "cat"
---
Traceback (most recent call last):
  File "/opt/homebrew/bin/rclip", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/opt/homebrew/Cellar/rclip/1.7.25/libexec/lib/python3.11/site-packages/rclip/main.py", line 205, in main
    arg_parser = helpers.init_arg_parser()
                 ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Cellar/rclip/1.7.25/libexec/lib/python3.11/site-packages/rclip/utils/helpers.py", line 144, in init_arg_parser
    if is_mps_available():
       ^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Cellar/rclip/1.7.25/libexec/lib/python3.11/site-packages/rclip/utils/helpers.py", line 153, in is_mps_available
    import torch.backends.mps
ModuleNotFoundError: No module named 'torch'

feat: option to do indexing without a query

Is there a way to run rclip without a query, just to update the index? Use case would be to have it run as a cron job so when a query needs to be run, there wouldn't be any waiting for indexing.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.