Skip to main content

🧿 Pupyl is a really fast image search library which you can index your own (millions of) images and find similar images in millisecond.

Project description

pupyl pupyl-ci codecov anaconda PyPI version Documentation Status Downloads CII Best Practices Anaconda-Server Badge

pupyl - A Python Image Search Library

pupyl

Table of contents

🧿 pupyl what?

The pupyl project (pronounced pyoo·piel) is a pythonic library to perform image search tasks (even over animated GIFs). It's intended to make easy reading, indexing, retrieving and maintaining a complete reverse image search engine. You can use it in your own data pipelines, web projects and wherever you find fit!

🎉 Getting started

📦 Installation

Installing pupyl on your environment is pretty easy:

# pypi
pip install pupyl

or

# anaconda
conda install -c policratus pupyl

For installation troubleshooting, visit troubleshooting.

🚸 Usage

You can call pupyl's objects directly from your application code. For this example, a sample database will be indexed and after that, the following image will be used as a query image (credits: @dlanor_s):

@dlanor_s

pupyl also supports using animated gifs as query images and can store and retrieve it too.

from pupyl.search import PupylImageSearch
from pupyl.web import interface

SEARCH = PupylImageSearch()

SEARCH.index(
    'https://github.com/policratus/pupyl'
    '/raw/main/samples/images.tar.xz'
)

# Using, for instance, a remote image. Local images have pretty faster results.
QUERY_IMAGE = 'https://images.unsplash.com/photo-1520763185298-1b434c919102?w=224&q=70'

[*SEARCH.search(QUERY_IMAGE)]

Disclaimer: the example above creates pupyl assets on your temporary directory. To define a non-volatile database, you should define data_dir parameter.

This will return:

# Here's the simplest possible result
> [486, 12, 203, 176]

With more information and returning image metadata from the results:

# The results with image metadata
[*SEARCH.search(QUERY_IMAGE, return_metadata=True)]

Now an excerpt of the (possible) return is:

[
    {
        "id": 486,
        "internal_path": "/tmp/pupyl/0/486.gif",
        "original_access_time": "2021-12-03T13:23:47",
        "original_file_name": "icegif-5690.gif",
        "original_file_size": "261K",
        "original_path": "/tmp/tmp3gdxlwr6"
    },
    {
        "id": 12,
        "internal_path": "/tmp/pupyl/0/12.gif",
        "original_access_time": "2021-12-03T13:23:46",
        "original_file_name": "roses.gif",
        "original_file_size": "1597K",
        "original_path": "/tmp/tmp3gdxlwr6"
    },
    ...
]

To interact visually, use the web interface:

# Opening the web interface
interface.serve()

A glimpse of the web interface, visualizing the results shown above:

web

Alternatively, you can interact with pupyl via command line. The same example above in CLI terms:

🐚 Command line interface

# Indexing images
pupyl --data_dir /path/to/your/data/dir index /path/to/images/

# Opening web interface
pupyl --data_dir /path/to/your/data/dir serve

# Searching using command line interface
pupyl --data_dir /path/to/your/data/dir search /path/to/query/image.ext

💡 Type pupyl --help to discover all the CLI's capabilities.

📌 Dependencies

See all dependencies here: dependencies.

📝 Documentation

See a getting started guide and the API reference on https://pupyl.readthedocs.io/.

🖊️ Citation

If you use pupyl in your publications or projects, please cite:

@misc{pupyl,
    author = {Nelson Forte de Souza Junior},
    title = {pupyl - A Python Image Search Library},
    howpublished = {\url{https://github.com/policratus/pupyl}},
    year = {2021}
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pupyl-0.14.7.tar.gz (47.5 kB view details)

Uploaded Source

Built Distribution

pupyl-0.14.7-py3-none-any.whl (40.1 kB view details)

Uploaded Python 3

File details

Details for the file pupyl-0.14.7.tar.gz.

File metadata

  • Download URL: pupyl-0.14.7.tar.gz
  • Upload date:
  • Size: 47.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for pupyl-0.14.7.tar.gz
Algorithm Hash digest
SHA256 9ae5fbc1de0024912f7cad0c6a5ff838516658de75e69a7d739d156e18b2bb7c
MD5 db3ab777414338f5a134c315ff36af6c
BLAKE2b-256 5f299297b8f6b8ab5fecb8e8370b17f5078b56649e1f53735d4e031522b1bf43

See more details on using hashes here.

File details

Details for the file pupyl-0.14.7-py3-none-any.whl.

File metadata

  • Download URL: pupyl-0.14.7-py3-none-any.whl
  • Upload date:
  • Size: 40.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for pupyl-0.14.7-py3-none-any.whl
Algorithm Hash digest
SHA256 4a21d95f888bbfd97164b725ea00608a4a543c830040fb2d00babf085145b402
MD5 26fe5886fed74e6d61cfacee3ba2b90a
BLAKE2b-256 31cc48b1b3085d7bacfb9d1713f7ced49c6ee78c94cddb82d71565f6da87243f

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page