Metadata-Version: 2.1
Name: imagecast
Version: 0.6.0
Summary: Imagecast is like ImageMagick but for Pythonistas. Optionally provides its features via HTTP API.
Home-page: https://github.com/panodata/imagecast
Author: Andreas Motl
Author-email: andreas.motl@panodata.org
License: AGPL 3, EUPL 1.2
Keywords: image conversion http api proxy
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Archiving
Classifier: Topic :: Utilities
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
License-File: LICENSE
Requires-Dist: docopt <1,>=0.6
Requires-Dist: munch <5,>=2.3
Requires-Dist: Pillow <11,>=8
Requires-Dist: playwright <1.41
Requires-Dist: requests <3,>=2.23
Requires-Dist: requests-cache <2,>=0.5
Provides-Extra: service
Requires-Dist: fastapi <0.106 ; extra == 'service'
Requires-Dist: uvicorn <0.25 ; extra == 'service'

.. image:: https://github.com/panodata/imagecast/actions/workflows/tests.yml/badge.svg
    :target: https://github.com/panodata/imagecast/actions/workflows/tests.yml

.. image:: https://img.shields.io/pypi/pyversions/imagecast.svg
    :target: https://python.org

.. image:: https://img.shields.io/pypi/v/imagecast.svg
    :target: https://pypi.org/project/imagecast/

.. image:: https://img.shields.io/pypi/status/imagecast.svg
    :target: https://pypi.org/project/imagecast/

.. image:: https://img.shields.io/pypi/l/imagecast.svg
    :target: https://pypi.org/project/imagecast/

.. image:: https://static.pepy.tech/badge/imagecast/month
    :target: https://pepy.tech/project/imagecast

|

.. imagecast-readme:

#########
Imagecast
#########


*****
About
*****

Imagecast is like ImageMagick but for Pythonistas. Optionally provides its
features via HTTP API.

Currently, this is based on Pillow_. However, it might be based on Wand_ in
the future.

There might still be dragons.

.. _Pillow: https://pillow.readthedocs.io/
.. _Wand: http://wand-py.org/


*******
Install
*******

Prerequisites
=============
::

    pip install imagecast

With service API::

    pip install imagecast[service]


********
Features
********

- Colorspace conversion: monochrome, grayscale
- Cropping with negative right/bottom offsets
- Resizing while keeping aspect ratio
- Output format: Any image formats from Pillow or raw bytes
- HTTP API


********
Synopsis
********

::

    # Display on screen
    imagecast --uri="$IMGURL" --display

    # Colorspace reduction to bi-level with threshold, output as bytes
    imagecast --uri="$IMGURL" --monochrome=200 --format=bytes

    # Colorspace reduction, cropping, resizing and format conversion
    imagecast --uri="$IMGURL" --grayscale --crop=40,50,-50,-40 --width=200 --save=test.png


Example::

    imagecast --uri="https://unsplash.com/photos/WvdKljW55rM/download?force=true" --monochrome=80 --crop=850,1925,-950,-900 --width=640 --display


HTML Capturing
==============

Imagecast can also capture screenshots of webpages, or elements thereof. It uses
`Playwright`_ and `Firefox`_ to convert full pages or specific DOM elements
to bitmaps.

After installing Imagecast, run::

    playwright install firefox

Then, invoke Imagecast like::

    imagecast --uri="${URL}" --display

In order to select specific elements for capturing, use the ``--element`` option
to express a DOM selector to apply::

    imagecast --uri="${URL}" --element="#panel-1" --display


HTTP API
========

Start the Imagecast service as daemon::

    imagecast service

Example::

    http "localhost:9999/?uri=https%3A%2F%2Funsplash.com%2Fphotos%2FWvdKljW55rM%2Fdownload%3Fforce%3Dtrue&monochrome=80&crop=850,1925,-950,-900&width=640"

.. note::

    You should not run the service without restricting the
    list of allowed remote hosts on the public internet.

    To do that, invoke the service like::

        imagecast service --allowed-hosts=unsplash.com,media.example.org


**************
Other projects
**************

- https://github.com/DictGet/ecce-homo
- https://github.com/agschwender/pilbox
- https://github.com/francescortiz/image


.. _Firefox: https://www.mozilla.org/firefox/
.. _Playwright: https://playwright.dev/
