# rclip - AI-Powered Command-Line Photo Search Tool
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->
[[Blog]](https://mikhalevi.ch/rclip-an-ai-powered-command-line-photo-search-tool/) [[Demo on YouTube]](https://www.youtube.com/watch?v=tAJHXOkHidw) [[Paper]](https://www.thinkmind.org/index.php?view=article&articleid=content_2023_1_20_60011)
<div align="center">
<img alt="rclip logo" src="https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/resources/logo-transparent.png" width="600px" />
</div>
**rclip** is a command-line photo search tool powered by the awesome OpenAI's [CLIP](https://github.com/openai/CLIP) neural network.
## Installation
### Linux
```bash
sudo snap install rclip
```
<details>
<summary>Alternative options (AppImage and <code>pip</code>)</summary>
If your Linux distribution doesn't support [snap](https://snapcraft.io/rclip), 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](https://github.com/yurijmikhalevich/rclip/releases).
2. Execute the following commands:
```bash
chmod +x <downloaded AppImage filename>
sudo mv <downloaded AppImage filename> /usr/local/bin/rclip
```
#### Using <code>pip</code>
```bash
pip install --extra-index-url https://download.pytorch.org/whl/cpu rclip
```
</details>
### macOS
```bash
brew install yurijmikhalevich/tap/rclip
```
<details>
<summary>Alternative option (<code>pip</code>)</summary>
```bash
pip install rclip
```
</details>
### Windows
1. Download the "*.msi" from the latest [release](https://github.com/yurijmikhalevich/rclip/releases).
2. Install **rclip** by running the installer.
<details>
<summary>Alternative option (<code>pip</code>)</summary>
```bash
pip install rclip
```
</details>
## Usage
```bash
cd photos && rclip "search query"
```
<img alt="rclip usage demo" src="https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/resources/rclip-usage.gif" width="640px" />
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:
```bash
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:
```bash
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](https://iterm2.com/), [Konsole](https://konsole.kde.org/) (version 22.04 and higher), [wezterm](https://wezfurlong.org/wezterm/), [Mintty](https://mintty.github.io/), or [mlterm](https://mlterm.sourceforge.net/) all you need to do is pass `--preview` (or `-p`) argument to **rclip**:
```bash
rclip -p kitty
```
<details>
<summary>Using a different terminal or viewer</summary>
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:
```bash
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:
```bash
rclip -f -t 5 kitty | feh -f - -t
```
</details>
## Get help
https://github.com/yurijmikhalevich/rclip/discussions/new/choose
## Contributing
This repository follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.
### Running locally from the source code
To run **rclip** locally from the source code, you must have [Python](https://www.python.org/downloads/) and [Poetry](https://python-poetry.org/) installed.
Then do:
```bash
# clone the source code repository
git clone git@github.com: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](#usage) section above.
## Contributors ✨
Thanks go to these wonderful people and organizations ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tbody>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/ramayer"><img src="https://avatars.githubusercontent.com/u/72320?v=4?s=100" width="100px;" alt="ramayer"/><br /><sub><b>ramayer</b></sub></a><br /><a href="https://github.com/yurijmikhalevich/rclip/commits?author=ramayer" title="Code">💻</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://www.caphyon.com"><img src="https://avatars.githubusercontent.com/u/15829334?v=4?s=100" width="100px;" alt="Caphyon"/><br /><sub><b>Caphyon</b></sub></a><br /><a href="#infra-Caphyon" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
</tr>
</tbody>
</table>
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
Thanks to [Caphyon](https://github.com/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](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/yurijmikhalevich/rclip",
"name": "rclip",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "image search, computer vision, photography",
"author": "Yurij Mikhalevich",
"author_email": "yurij@mikhalevi.ch",
"download_url": "https://files.pythonhosted.org/packages/7f/1b/6b5ec25b51b514fefe76566457b23397719452f16eab41e51bb2fa49f08e/rclip-1.10.3.tar.gz",
"platform": null,
"description": "# rclip - AI-Powered Command-Line Photo Search Tool\n<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->\n[](#contributors-)\n<!-- ALL-CONTRIBUTORS-BADGE:END -->\n\n[[Blog]](https://mikhalevi.ch/rclip-an-ai-powered-command-line-photo-search-tool/) [[Demo on YouTube]](https://www.youtube.com/watch?v=tAJHXOkHidw) [[Paper]](https://www.thinkmind.org/index.php?view=article&articleid=content_2023_1_20_60011)\n\n<div align=\"center\">\n <img alt=\"rclip logo\" src=\"https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/resources/logo-transparent.png\" width=\"600px\" />\n</div>\n\n**rclip** is a command-line photo search tool powered by the awesome OpenAI's [CLIP](https://github.com/openai/CLIP) neural network.\n\n## Installation\n\n### Linux\n\n```bash\nsudo snap install rclip\n```\n\n<details>\n <summary>Alternative options (AppImage and <code>pip</code>)</summary>\n\n If your Linux distribution doesn't support [snap](https://snapcraft.io/rclip), you can use one of the alternative installation options:\n\n #### AppImage (self-contained x86_64 executable)\n\n On Linux x86_64, you can install **rclip** as a self-contained executable.\n\n 1. Download the AppImage from the latest [release](https://github.com/yurijmikhalevich/rclip/releases).\n\n 2. Execute the following commands:\n\n ```bash\n chmod +x <downloaded AppImage filename>\n sudo mv <downloaded AppImage filename> /usr/local/bin/rclip\n ```\n\n #### Using <code>pip</code>\n\n ```bash\n pip install --extra-index-url https://download.pytorch.org/whl/cpu rclip\n ```\n</details>\n\n### macOS\n\n```bash\nbrew install yurijmikhalevich/tap/rclip\n```\n\n<details>\n <summary>Alternative option (<code>pip</code>)</summary>\n\n ```bash\n pip install rclip\n ```\n</details>\n\n### Windows\n\n1. Download the \"*.msi\" from the latest [release](https://github.com/yurijmikhalevich/rclip/releases).\n2. Install **rclip** by running the installer.\n\n<details>\n <summary>Alternative option (<code>pip</code>)</summary>\n\n ```bash\n pip install rclip\n ```\n</details>\n\n## Usage\n\n```bash\ncd photos && rclip \"search query\"\n```\n\n<img alt=\"rclip usage demo\" src=\"https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/resources/rclip-usage.gif\" width=\"640px\" />\n\nWhen 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\u00a0Celeron\u00a0J3455, 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.\n\nFor a detailed demonstration, watch the video: https://www.youtube.com/watch?v=tAJHXOkHidw.\n\n### Similar image search\n\nYou 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:\n\n```bash\ncd photos && rclip ./cat.jpg\n\n# or use URL\ncd photos && rclip https://raw.githubusercontent.com/yurijmikhalevich/rclip/main/tests/e2e/images/cat.jpg\n```\n\nCheck this video out for the image-to-image search demo: https://www.youtube.com/watch?v=1YQZKeCBxWM.\n\n### Combining multiple queries\n\nYou can add and subtract image and text queries from each other; here are a few usage examples:\n\n```bash\ncd photos && rclip horse + stripes\ncd photos && rclip apple - fruit\ncd photos && rclip \"./new york city.jpg\" + night\ncd photos && rclip \"2:golden retriever\" + \"./swimming pool.jpg\"\ncd photos && rclip \"./racing car.jpg\" - \"2:sports car\" + \"2:snow\"\n```\n\nIf 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.\n\n### How do I preview the results?\n\nIf you are using either one of [iTerm2](https://iterm2.com/), [Konsole](https://konsole.kde.org/) (version 22.04 and higher), [wezterm](https://wezfurlong.org/wezterm/), [Mintty](https://mintty.github.io/), or [mlterm](https://mlterm.sourceforge.net/) all you need to do is pass `--preview` (or `-p`) argument to **rclip**:\n\n```bash\nrclip -p kitty\n```\n\n<details>\n <summary>Using a different terminal or viewer</summary>\n\n 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:\n\n ```bash\n rclip -f -t 5 kitty | xargs -d '\\n' -n 1 xdg-open\n ```\n\n 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.\n \n I prefer to use **feh**'s thumbnail mode to preview multiple results:\n\n ```bash\n rclip -f -t 5 kitty | feh -f - -t\n ```\n</details>\n\n## Get help\n\nhttps://github.com/yurijmikhalevich/rclip/discussions/new/choose\n\n## Contributing\n\nThis repository follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.\n\n### Running locally from the source code\n\nTo run **rclip** locally from the source code, you must have [Python](https://www.python.org/downloads/) and [Poetry](https://python-poetry.org/) installed.\n\nThen do:\n```bash\n# clone the source code repository\ngit clone git@github.com:yurijmikhalevich/rclip.git\n\n# install dependencies and rclip\ncd rclip\npoetry install\n\n# activate the new poetry environment\npoetry shell\n```\n\nIf the poetry environment is active, you can use **rclip** locally, as described in the [Usage](#usage) section above.\n\n## Contributors \u2728\n\nThanks go to these wonderful people and organizations ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n<table>\n <tbody>\n <tr>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/ramayer\"><img src=\"https://avatars.githubusercontent.com/u/72320?v=4?s=100\" width=\"100px;\" alt=\"ramayer\"/><br /><sub><b>ramayer</b></sub></a><br /><a href=\"https://github.com/yurijmikhalevich/rclip/commits?author=ramayer\" title=\"Code\">\ud83d\udcbb</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://www.caphyon.com\"><img src=\"https://avatars.githubusercontent.com/u/15829334?v=4?s=100\" width=\"100px;\" alt=\"Caphyon\"/><br /><sub><b>Caphyon</b></sub></a><br /><a href=\"#infra-Caphyon\" title=\"Infrastructure (Hosting, Build-Tools, etc)\">\ud83d\ude87</a></td>\n </tr>\n </tbody>\n</table>\n\n<!-- markdownlint-restore -->\n<!-- prettier-ignore-end -->\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\nThanks to [Caphyon](https://github.com/Caphyon) and Advanced Installer team for generously supplying **rclip** project with the Professional Advanced Installer license for creating the Windows installer.\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!\n\n## License\n\nMIT\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-Powered Command-Line Photo Search Tool",
"version": "1.10.3",
"project_urls": {
"Homepage": "https://github.com/yurijmikhalevich/rclip",
"Repository": "https://github.com/yurijmikhalevich/rclip"
},
"split_keywords": [
"image search",
" computer vision",
" photography"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e0928640861d6e276ea585914de5301bb8b555e5b920e610dfb8cc2e6bd527de",
"md5": "ee2fb4a52a3f3e1de302e6db236c6c90",
"sha256": "315a83b7a2da6c0edfbc2ff17db6002c2795965725fd847a28aee43a17559126"
},
"downloads": -1,
"filename": "rclip-1.10.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee2fb4a52a3f3e1de302e6db236c6c90",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 16945,
"upload_time": "2024-08-17T06:03:15",
"upload_time_iso_8601": "2024-08-17T06:03:15.573098Z",
"url": "https://files.pythonhosted.org/packages/e0/92/8640861d6e276ea585914de5301bb8b555e5b920e610dfb8cc2e6bd527de/rclip-1.10.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7f1b6b5ec25b51b514fefe76566457b23397719452f16eab41e51bb2fa49f08e",
"md5": "2ddd0613d07715126c7be962c6412c13",
"sha256": "dca80443246714b305f9b98858b34a0b699526cb6805713b3f5ac2d11c10475e"
},
"downloads": -1,
"filename": "rclip-1.10.3.tar.gz",
"has_sig": false,
"md5_digest": "2ddd0613d07715126c7be962c6412c13",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 17239,
"upload_time": "2024-08-17T06:03:17",
"upload_time_iso_8601": "2024-08-17T06:03:17.442511Z",
"url": "https://files.pythonhosted.org/packages/7f/1b/6b5ec25b51b514fefe76566457b23397719452f16eab41e51bb2fa49f08e/rclip-1.10.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-17 06:03:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yurijmikhalevich",
"github_project": "rclip",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rclip"
}
JSON
