{"id":16568399,"url":"https://github.com/breezedeus/coin-clip","last_synced_at":"2026-03-05T00:35:38.820Z","repository":{"id":211099710,"uuid":"723612718","full_name":"breezedeus/Coin-CLIP","owner":"breezedeus","description":" Coin-CLIP: fine-tuned with a vast collection of coin images from CLIP using contrastive learning. It enhances feature extraction for coins, boosting image search accuracy. This model merges Visual Transformer (ViT) with CLIP's multimodal learning, optimized for numismatic applications.","archived":false,"fork":false,"pushed_at":"2023-12-08T09:25:21.000Z","size":52780,"stargazers_count":16,"open_issues_count":4,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-28T16:52:12.158Z","etag":null,"topics":["clip","coin","coin-identification","coin-recognition","coin-retrieval","multimodal-learning","numismatics"],"latest_commit_sha":null,"homepage":"https://huggingface.co/spaces/breezedeus/USA-Coin-Retrieval","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/breezedeus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-26T08:11:30.000Z","updated_at":"2024-11-28T06:38:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"cdb3a2a4-2778-49e8-a2ed-ac35489172d0","html_url":"https://github.com/breezedeus/Coin-CLIP","commit_stats":null,"previous_names":["breezedeus/coin-clip"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezedeus%2FCoin-CLIP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezedeus%2FCoin-CLIP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezedeus%2FCoin-CLIP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezedeus%2FCoin-CLIP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/breezedeus","download_url":"https://codeload.github.com/breezedeus/Coin-CLIP/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227772825,"owners_count":17817780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clip","coin","coin-identification","coin-recognition","coin-retrieval","multimodal-learning","numismatics"],"created_at":"2024-10-11T21:09:23.260Z","updated_at":"2026-03-05T00:35:33.793Z","avatar_url":"https://github.com/breezedeus.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/coin-clip-logo.png\" width=\"160px\"/\u003e\n  \u003cdiv\u003e\u0026nbsp;\u003c/div\u003e\n\n[![Downloads](https://static.pepy.tech/personalized-badge/coin_clip?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=orange\u0026left_text=Downloads)](https://pepy.tech/project/coin_clip)\n[![license](https://img.shields.io/github/license/breezedeus/coin-clip)](./LICENSE)\n[![PyPI version](https://badge.fury.io/py/coin_clip.svg)](https://badge.fury.io/py/coin_clip)\n[![forks](https://img.shields.io/github/forks/breezedeus/coin-clip)](https://github.com/breezedeus/coin-clip)\n[![stars](https://img.shields.io/github/stars/breezedeus/coin-clip)](https://github.com/breezedeus/coin-clip)\n![last-releast](https://img.shields.io/github/release-date/breezedeus/coin-clip)\n![last-commit](https://img.shields.io/github/last-commit/breezedeus/coin-clip)\n[![Twitter](https://img.shields.io/twitter/url?url=https%3A%2F%2Ftwitter.com%2Fbreezedeus)](https://twitter.com/breezedeus)\n\n[🧳 Model](https://huggingface.co/breezedeus/coin-clip-vit-base-patch32) |\n[🛀🏻 Online Demo](https://huggingface.co/spaces/breezedeus/USA-Coin-Retrieval) |\n[💬 Contact](https://www.breezedeus.com/join-group)\n\n\u003c/div\u003e\n\n \u003cdiv align=\"center\"\u003e\n \u003cstrong\u003e\n\n[[中文]](./README_cn.md) | [English]\n\n \u003c/strong\u003e\n\u003c/div\u003e\n\n# Coin-CLIP 🪙 : Enhancing Coin Image Retrieval with CLIP\n\n**[Coin-CLIP](https://huggingface.co/breezedeus/coin-clip-vit-base-patch32)** `breezedeus/coin-clip-vit-base-patch32` is built upon \nOpenAI's **[CLIP](https://huggingface.co/openai/clip-vit-base-patch32) (ViT-B/32)** model and fine-tuned on \na dataset of more than `340,000` coin images using contrastive learning techniques. This specialized model is designed to significantly improve feature extraction for coin images, leading to more accurate image-based search capabilities. Coin-CLIP combines the power of Visual Transformer (ViT) with CLIP's multimodal learning capabilities, specifically tailored for the numismatic domain.\n\n**Key Features:**\n- State-of-the-art coin image retrieval;\n- Enhanced feature extraction for numismatic images;\n- Seamless integration with CLIP's multimodal learning.\n\n\nTo further simplify the use of the **Coin-CLIP** model, this project provides tools for quickly building a coin image retrieval engine.\n\n# Comparison: Coin-CLIP vs. CLIP\n\n#### Example 1 (Left: Coin-CLIP; Right: CLIP)\n\n![1. Coin-CLIP vs. CLIP](./docs/images/3-c.gif)\n\n#### Example 2 (Left: Coin-CLIP; Right: CLIP)\n\n![2. Coin-CLIP vs. CLIP](./docs/images/5-c.gif)\n\n#### More Examples\n\n\u003cdetails\u003e\n\n\u003csummary\u003emore\u003c/summary\u003e\n\nExample 3 (Left: Coin-CLIP; Right: CLIP)\n![3. Coin-CLIP vs. CLIP](./docs/images/1-c.gif)\n\nExample 4 (Left: Coin-CLIP; Right: CLIP)\n![4. Coin-CLIP vs. CLIP](./docs/images/4-c.gif)\n\nExample 5 (Left: Coin-CLIP; Right: CLIP)\n![5. Coin-CLIP vs. CLIP](./docs/images/2-c.gif)\n\nExample 6 (Left: Coin-CLIP; Right: CLIP)\n![6. Coin-CLIP vs. CLIP](./docs/images/6-c.gif)\n\n\u003c/details\u003e\n\n# Install\n\n```bash\npip install coin_clip\n```\n\n# Usage\n## Code Examples\n\n### Extract Feature Vectors from Coin Images\n\n```python\nfrom coin_clip import CoinClip\n\n# Automatically download the model from Huggingface\nmodel = CoinClip(model_name='breezedeus/coin-clip-vit-base-patch32')\nimages = ['examples/10_back.jpg', 'examples/16_back.jpg']\nimg_feats, success_ids = model.get_image_features(images)\nprint(img_feats.shape)  # --\u003e (2, 512)\n```\n\n\u003e ⚠️ **Note**:\n\u003e \n\u003e The above code automatically downloads the [`breezedeus/coin-clip-vit-base-patch32`](https://huggingface.co/breezedeus/coin-clip-vit-base-patch32) model from Huggingface.\nIf you cannot download automatically, please manually download the model locally, and then initialize `CoinClip` by specifying the local directory of the model through the `model_name` parameter, like `model_name='path/to/coin-clip-vit-base-patch32'`.\n\n## Command line tools\n\n### Building a Vector Retrieval Engine\n\n`coin-clip build-db` can be used to build a vector search engine. It extracts features from all coin images 🪙 in a specified directory and builds a ChromaDB vector search engine.\n\n```bash\n$ coin-clip build-db -h\nUsage: coin-clip build-db [OPTIONS]\n\n  Extract vectors from a candidate image set and build a search engine based\n  on it.\n\nOptions:\n  -m, --model-name TEXT       Model Name; either local path or huggingface\n                              model name  [default: breezedeus/coin-clip-vit-\n                              base-patch32]\n  -d, --device TEXT           ['cpu', 'cuda']; Either 'cpu' or 'gpu', or\n                              specify a specific GPU like 'cuda:0'. Default is\n                              'cpu'.  [default: cpu]\n  -i, --input-image-dir TEXT  Folder with Coin Images to be indexed. [required]\n  -o, --output-db-dir TEXT    Folder where the built search engine is stored.\n                              [default: ./coin_clip_chroma.db]\n  -h, --help                  Show this message and exit.\n```\n\nFor instance, \n\n```bash\n$ coin-clip build-db -i examples -o coin_clip_chroma.db\n```\n\n### Querying\nAfter building the vector search engine with the above command, you can use the `coin-clip retrieve` command to retrieve the coin images 🪙 most similar to a specified coin image.\n\n```bash\n$ coin-clip retrieve -h\nUsage: coin-clip retrieve [OPTIONS]\n\n  Retrieve images from the search engine, based on the query image.\n\nOptions:\n  -m, --model-name TEXT  Model Name; either local path or huggingface model\n                         name  [default: breezedeus/coin-clip-vit-base-\n                         patch32]\n  -d, --device TEXT      ['cpu', 'cuda']; Either 'cpu' or 'gpu', or specify a\n                         specific GPU like 'cuda:0'. Default is 'cpu'.\n                         [default: cpu]\n  --db-dir TEXT          Folder where the built search engine is stored.\n                         [default: ./coin_clip_chroma.db]\n  -i, --image-fp TEXT    Image Path to retrieve  [required]\n  -h, --help             Show this message and exit.\n```\n\nFor instance, \n\n```bash\n$ coin-clip retrieve --db-dir coin_clip_chroma.db -i examples/10_back.jpg\n```\n\n\n## A cup of coffee for the author\n\nIt is not easy to maintain and evolve the project, so if it is helpful to you, please consider [offering the author a cup of coffee 🥤](https://www.breezedeus.com/buy-me-coffee).\n\n---\n\nOfficial code base: [https://github.com/breezedeus/coin-clip](https://github.com/breezedeus/coin-clip). Please cite it properly.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreezedeus%2Fcoin-clip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbreezedeus%2Fcoin-clip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreezedeus%2Fcoin-clip/lists"}