| Name | eyepop JSON |
| Version |
1.6.1
JSON |
| download |
| home_page | None |
| Summary | EyePop.ai Python SDK |
| upload_time | 2024-12-08 00:56:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License Copyright (c) 2023 EyePop.ai Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
eyepop
ai
ml
cv
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# EyePop.ai Python SDK
The EyePop.ai Python SDK provides convenient access to the EyePop.ai's inference API from applications written in the
Python language.
## Requirements
* Python 3.8+
## Install
```shell
pip install eyepop
```
## Configuration
The EyePop SDK needs to be configured with the __Pop Id__ and your __Secret Api Key__.
```python
import os
from eyepop import EyePopSdk
endpoint = EyePopSdk.workerEndpoint(
# This is the default and can be omitted
pop_id=os.environ.get('EYEPOP_POP_ID'),
# This is the default and can be omitted
secret_key=os.environ.get('EYEPOP_SECRET_KEY'),
)
endpoint.connect()
# do work ....
endpoint.disconnect()
```
While you can provide a secret_key keyword argument, we recommend using python-dotenv to add EYEPOP_SECRET_KEY="My API Key"
to your .env file so that your API Key is not stored in source control. By default, the SDK will read the following environment variables:
* `EYEPOP_POP_ID`: The Pop Id to use as an endpoint. You can copy'n paste this string from your EyePop Dashboard in the Pop -> Settings section.
* `EYEPOP_SECRET_KEY`: Your Secret Api Key. You can create Api Keys in the profile section of youe EyePop dashboard.
* `EYEPOP_URL`: (Optional) URL of the EyePop API service, if you want to use any other endpoint than production `http://api.eyepop.ai`
## Usage Examples
### Uploading and processing one single image
```python
from eyepop import EyePopSdk
def upload_photo(file_path: str):
with EyePopSdk.workerEndpoint() as endpoint:
result = endpoint.upload(file_path).predict()
print(result)
upload_photo('examples/example.jpg')
```
1. `EyePopSdk.workerEndpoint()` returns a local endpoint object, that will authenticate with the Api Key found in
EYEPOP_SECRET_KEY and load the worker configuration for the Pop identified by EYEPOP_POP_ID.
2. The usage of `with ... endpoint:` will automatically manage the runtime context, connect to the worker upon entering
the context and releasing all underlying resources upon exiting the context. Alternatively your code can call
endpoint.connect() before any job is submitted and endpoint.disconnect() to release all resources.
2. `endpoint.upload('examples/example.jpg')` initiates the upload to the local file to the worker service. The image will
be queued and processed immediately when the worker becomes available.
3. `predict()` waits for the first prediction result as reports it as a dict. In case of a single image, there will be
one single prediction result and subsequent calls to predict() will return None. If the uploaded file is a video
e.g. 'video/mp4' or image container format e.g. 'image/gif', subsequent calls to predict() will return a prediction
for each individual frame and None when the entire file has been processed.
Note: since v0.19.0 `EyePopSdk.workerEndpoint()` was introduced and replaces `EyePopSdk.endpoint()` which is now deprecated.
Support for `EyePopSdk.endpoint()` will be removed in v1.0.0.
To upload a binary stream, i.e. a file-like object, you can use the method `upload_stream()` and pass the file-like
object and the mime-type:
```python
from eyepop import EyePopSdk
def upload_photo_from_stream(file_path: str, mime_type: str):
with EyePopSdk.workerEndpoint() as endpoint:
with open(file_path, 'rb') as file:
result = endpoint.upload_stream(file, mime_type).predict()
print(result)
upload_photo_from_stream('examples/example.jpg', 'image/jpeg')
```
### Visualizing Results
The EyePop SDK includes helper classes to to visualize bounding boxes `matplotlib.pyplot`.
```python
from PIL import Image
import matplotlib.pyplot as plt
from eyepop import EyePopSdk
with EyePopSdk.workerEndpoint() as endpoint:
result = endpoint.upload('examples/example.jpg').predict()
with Image.open('examples/example.jpg') as image:
plt.imshow(image)
plot = EyePopSdk.plot(plt.gca())
plot.prediction(result)
plt.show()
```
Depending on the environment, you might need to install an interactive backend, e.g. with `pip3 install pyqt5`.
EyePop's Python Sdk does not include visualization helpers for any other prediction types than object bounding boxes.
Check out [visualize_with_webui2.py](examples/visualize_with_webui2.py) for an example how to use the comprehensive visualization support provided by the EyePop Node Sdk.
### Uploading and processing batches of images
For batches of images, instead of waiting for each result `predict()` _before_ submitting the next job, you can queue
all jobs first, let them process in parallel and collect the results later. This avoids the sequential accumulation of
the HTTP roundtrip time.
```python
from eyepop import EyePopSdk
def upload_photos(file_paths: list[str]):
with EyePopSdk.workerEndpoint() as endpoint:
jobs = []
for file_path in file_paths:
jobs.append(endpoint.upload(file_path))
for job in jobs:
print(job.predict())
upload_photos(['examples/example.jpg'] * 100)
```
### Asynchronous uploading and processing of images
The above _synchronous_ way is great for individual images or reasonable sized batches. If your batch size is 'large'
this can cause memory and performance issues. Consider that `endpoint.upload()` is a very fast, local operation.
In fact, it creates and schedules a task that will execute the 'slow' IO operations in the background. Consequently,
when your code calls `enpoint.upload()` 1,000,000 times it will cause a background task list with ~ 1,000,000 entries.
And the example code above will only start clearing out this list by receiving the result via `predict()` after the
entire list was submitted.
For high throughput applications, consider using the `async` variant which supports a callback parameter `on_ready`.
Within the callback, your code can process the results asynchronously and clearing the task list as soon as the results
are available.
```python
import asyncio
from eyepop import EyePopSdk
from eyepop import Job
async def async_upload_photos(file_paths: list[str]):
async def on_ready(job: Job):
print(await job.predict())
async with EyePopSdk.workerEndpoint(is_async=True) as endpoint:
for file_path in file_paths:
await endpoint.upload(file_path, on_ready=on_ready)
asyncio.run(async_upload_photos(['examples/example.jpg'] * 100000000))
```
### Loading images from URLs
Alternatively to uploading files, you can also submit a publicly accessible URL for processing. This works for both,
synchronous and asynchronous mode. Supported protocols are:
* HTTP(s) URLs with response Content-Type image/* or video/*
* RTSP (live streaming)
* RTMP (live streaming)
```python
from eyepop import EyePopSdk
def load_from_url(url: str):
with EyePopSdk.workerEndpoint() as endpoint:
result = endpoint.load_from(url).predict()
print(result)
load_from_url('https://farm2.staticflickr.com/1080/1301049949_532835a8b5_z.jpg')
```
### Processing Videos
You can process videos via upload or public URLs. This example shows how to process all video frames of a file
retrieved from a public URL. This works for both, synchronous and asynchronous mode.
```python
from eyepop import EyePopSdk
def load_video_from_url(url: str):
with EyePopSdk.workerEndpoint() as endpoint:
job = endpoint.load_from(url)
while result := job.predict():
print(result)
load_video_from_url('https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4')
```
### Canceling Jobs
Any job that has been queued or is in-progress can be cancelled. E.g. stop the video processing after
predictions have been processed for 10 seconds duration of the video.
```python
from eyepop import EyePopSdk
def load_video_from_url(url: str):
with EyePopSdk.workerEndpoint() as endpoint:
job = endpoint.load_from(url)
while result := job.predict():
print(result)
if result['seconds'] >= 10.0:
job.cancel()
load_video_from_url('https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4')
```
## Other Usage Options
#### Auto start workers
By default, `EyePopSdk.workerEndpoint().connect()` will start a worker if none is running yet. To disable this behavior
create an endpoint with `EyePopSdk.endpoint(auto_start=False)`.
#### Stop pending jobs
By default, `EyePopSdk.workerEndpoint().connect()` will cancel all currently running or queued jobs on the worker.
It is assumed that the caller _takes full control_ of that worker. To disable this behavior create an endpoint with
`EyePopSdk.workerEndpoint(stop_jobs=False)`.
## Data endpoint (experimental)
To support managing your own datasets and control model optimization v0.19.0 introduces `EyePopSdk.dataEndpoint()`,
an experimental pre-release which is subject to change. An officially supported version will be released with v1.0.0
## Composable Pops (PREVIEW)
See [Composable Pops](https://github.com/eyepop-ai/eyepop-sdk-node/blob/main/src/eyepop/composable-pops.md)
for a preview of client side composability of pops, introduced in v1.0.0.
Raw data
{
"_id": null,
"home_page": null,
"name": "eyepop",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "EyePop, AI, ML, CV",
"author": null,
"author_email": "\"EyePop.ai\" <support@eyepop.ai>",
"download_url": "https://files.pythonhosted.org/packages/3e/d9/a2c473a06b5a67c1bf88cb9e868bfa4f39e51d9496ea81826ebe4ee0b0d6/eyepop-1.6.1.tar.gz",
"platform": null,
"description": "# EyePop.ai Python SDK\nThe EyePop.ai Python SDK provides convenient access to the EyePop.ai's inference API from applications written in the \nPython language. \n\n## Requirements \n* Python 3.8+\n\n## Install\n```shell\npip install eyepop\n```\n\n## Configuration\nThe EyePop SDK needs to be configured with the __Pop Id__ and your __Secret Api Key__.\n\n```python\nimport os\nfrom eyepop import EyePopSdk\n\nendpoint = EyePopSdk.workerEndpoint(\n # This is the default and can be omitted\n pop_id=os.environ.get('EYEPOP_POP_ID'),\n # This is the default and can be omitted\n secret_key=os.environ.get('EYEPOP_SECRET_KEY'),\n)\n\nendpoint.connect()\n# do work ....\nendpoint.disconnect()\n```\nWhile you can provide a secret_key keyword argument, we recommend using python-dotenv to add EYEPOP_SECRET_KEY=\"My API Key\" \nto your .env file so that your API Key is not stored in source control. By default, the SDK will read the following environment variables:\n* `EYEPOP_POP_ID`: The Pop Id to use as an endpoint. You can copy'n paste this string from your EyePop Dashboard in the Pop -> Settings section.\n* `EYEPOP_SECRET_KEY`: Your Secret Api Key. You can create Api Keys in the profile section of youe EyePop dashboard.\n* `EYEPOP_URL`: (Optional) URL of the EyePop API service, if you want to use any other endpoint than production `http://api.eyepop.ai` \n## Usage Examples\n \n### Uploading and processing one single image\n\n```python\nfrom eyepop import EyePopSdk\n\n\ndef upload_photo(file_path: str):\n with EyePopSdk.workerEndpoint() as endpoint:\n result = endpoint.upload(file_path).predict()\n print(result)\n\n\nupload_photo('examples/example.jpg')\n```\n1. `EyePopSdk.workerEndpoint()` returns a local endpoint object, that will authenticate with the Api Key found in \nEYEPOP_SECRET_KEY and load the worker configuration for the Pop identified by EYEPOP_POP_ID. \n2. The usage of `with ... endpoint:` will automatically manage the runtime context, connect to the worker upon entering\nthe context and releasing all underlying resources upon exiting the context. Alternatively your code can call \nendpoint.connect() before any job is submitted and endpoint.disconnect() to release all resources.\n2. `endpoint.upload('examples/example.jpg')` initiates the upload to the local file to the worker service. The image will\nbe queued and processed immediately when the worker becomes available.\n3. `predict()` waits for the first prediction result as reports it as a dict. In case of a single image, there will be \none single prediction result and subsequent calls to predict() will return None. If the uploaded file is a video\ne.g. 'video/mp4' or image container format e.g. 'image/gif', subsequent calls to predict() will return a prediction \nfor each individual frame and None when the entire file has been processed.\n\nNote: since v0.19.0 `EyePopSdk.workerEndpoint()` was introduced and replaces `EyePopSdk.endpoint()` which is now deprecated. \nSupport for `EyePopSdk.endpoint()` will be removed in v1.0.0.\n\nTo upload a binary stream, i.e. a file-like object, you can use the method `upload_stream()` and pass the file-like \nobject and the mime-type:\n\n```python\nfrom eyepop import EyePopSdk\n\n\ndef upload_photo_from_stream(file_path: str, mime_type: str):\n with EyePopSdk.workerEndpoint() as endpoint:\n with open(file_path, 'rb') as file:\n result = endpoint.upload_stream(file, mime_type).predict()\n print(result)\n\n\nupload_photo_from_stream('examples/example.jpg', 'image/jpeg')\n```\n\n### Visualizing Results\nThe EyePop SDK includes helper classes to to visualize bounding boxes `matplotlib.pyplot`.\n\n```python\nfrom PIL import Image\nimport matplotlib.pyplot as plt\nfrom eyepop import EyePopSdk\n\nwith EyePopSdk.workerEndpoint() as endpoint:\n result = endpoint.upload('examples/example.jpg').predict()\nwith Image.open('examples/example.jpg') as image:\n plt.imshow(image)\nplot = EyePopSdk.plot(plt.gca())\nplot.prediction(result)\nplt.show()\n```\nDepending on the environment, you might need to install an interactive backend, e.g. with `pip3 install pyqt5`. \nEyePop's Python Sdk does not include visualization helpers for any other prediction types than object bounding boxes.\nCheck out [visualize_with_webui2.py](examples/visualize_with_webui2.py) for an example how to use the comprehensive visualization support provided by the EyePop Node Sdk.\n\n### Uploading and processing batches of images\nFor batches of images, instead of waiting for each result `predict()` _before_ submitting the next job, you can queue \nall jobs first, let them process in parallel and collect the results later. This avoids the sequential accumulation of \nthe HTTP roundtrip time.\n\n```python\nfrom eyepop import EyePopSdk\n\n\ndef upload_photos(file_paths: list[str]):\n with EyePopSdk.workerEndpoint() as endpoint:\n jobs = []\n for file_path in file_paths:\n jobs.append(endpoint.upload(file_path))\n for job in jobs:\n print(job.predict())\n\n\nupload_photos(['examples/example.jpg'] * 100)\n```\n### Asynchronous uploading and processing of images\nThe above _synchronous_ way is great for individual images or reasonable sized batches. If your batch size is 'large'\nthis can cause memory and performance issues. Consider that `endpoint.upload()` is a very fast, local operation. \nIn fact, it creates and schedules a task that will execute the 'slow' IO operations in the background. Consequently, \nwhen your code calls `enpoint.upload()` 1,000,000 times it will cause a background task list with ~ 1,000,000 entries. \nAnd the example code above will only start clearing out this list by receiving the result via `predict()` after the \nentire list was submitted.\n\nFor high throughput applications, consider using the `async` variant which supports a callback parameter `on_ready`. \nWithin the callback, your code can process the results asynchronously and clearing the task list as soon as the results \nare available.\n\n```python\nimport asyncio\nfrom eyepop import EyePopSdk\nfrom eyepop import Job\n\n\nasync def async_upload_photos(file_paths: list[str]):\n async def on_ready(job: Job):\n print(await job.predict())\n\n async with EyePopSdk.workerEndpoint(is_async=True) as endpoint:\n for file_path in file_paths:\n await endpoint.upload(file_path, on_ready=on_ready)\n\n\nasyncio.run(async_upload_photos(['examples/example.jpg'] * 100000000))\n```\n### Loading images from URLs\nAlternatively to uploading files, you can also submit a publicly accessible URL for processing. This works for both,\nsynchronous and asynchronous mode. Supported protocols are:\n* HTTP(s) URLs with response Content-Type image/* or video/* \n* RTSP (live streaming)\n* RTMP (live streaming)\n\n```python\nfrom eyepop import EyePopSdk\n\n\ndef load_from_url(url: str):\n with EyePopSdk.workerEndpoint() as endpoint:\n result = endpoint.load_from(url).predict()\n print(result)\n\n\nload_from_url('https://farm2.staticflickr.com/1080/1301049949_532835a8b5_z.jpg')\n```\n### Processing Videos \nYou can process videos via upload or public URLs. This example shows how to process all video frames of a file \nretrieved from a public URL. This works for both, synchronous and asynchronous mode.\n\n```python\nfrom eyepop import EyePopSdk\n\n\ndef load_video_from_url(url: str):\n with EyePopSdk.workerEndpoint() as endpoint:\n job = endpoint.load_from(url)\n while result := job.predict():\n print(result)\n\n\nload_video_from_url('https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4')\n```\n### Canceling Jobs\nAny job that has been queued or is in-progress can be cancelled. E.g. stop the video processing after\npredictions have been processed for 10 seconds duration of the video.\n\n```python\nfrom eyepop import EyePopSdk\n\n\ndef load_video_from_url(url: str):\n with EyePopSdk.workerEndpoint() as endpoint:\n job = endpoint.load_from(url)\n while result := job.predict():\n print(result)\n if result['seconds'] >= 10.0:\n job.cancel()\n\n\nload_video_from_url('https://demo-eyepop-videos.s3.amazonaws.com/test1_vlog.mp4')\n```\n## Other Usage Options\n#### Auto start workers\nBy default, `EyePopSdk.workerEndpoint().connect()` will start a worker if none is running yet. To disable this behavior \ncreate an endpoint with `EyePopSdk.endpoint(auto_start=False)`.\n#### Stop pending jobs\nBy default, `EyePopSdk.workerEndpoint().connect()` will cancel all currently running or queued jobs on the worker. \nIt is assumed that the caller _takes full control_ of that worker. To disable this behavior create an endpoint with \n`EyePopSdk.workerEndpoint(stop_jobs=False)`.\n\n## Data endpoint (experimental)\nTo support managing your own datasets and control model optimization v0.19.0 introduces `EyePopSdk.dataEndpoint()`,\nan experimental pre-release which is subject to change. An officially supported version will be released with v1.0.0\n\n## Composable Pops (PREVIEW)\nSee [Composable Pops](https://github.com/eyepop-ai/eyepop-sdk-node/blob/main/src/eyepop/composable-pops.md) \nfor a preview of client side composability of pops, introduced in v1.0.0.\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 EyePop.ai Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "EyePop.ai Python SDK",
"version": "1.6.1",
"project_urls": {
"Homepage": "https://github.com/eyepop-ai/eyepop-sdk-python",
"Repository": "https://github.com/eyepop-ai/eyepop-sdk-python"
},
"split_keywords": [
"eyepop",
" ai",
" ml",
" cv"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c7c3b90ced8aa0ccbe12421a7f488ba87898137fdb0c04ca88664b513a9aa83f",
"md5": "7ceeda933d29ea5b0f691a1dda56f546",
"sha256": "dba08b6b0b185494b707577782e0ba4e2e4ee936031af39517e0910ab5fd3060"
},
"downloads": -1,
"filename": "eyepop-1.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7ceeda933d29ea5b0f691a1dda56f546",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 41542,
"upload_time": "2024-12-08T00:56:34",
"upload_time_iso_8601": "2024-12-08T00:56:34.259549Z",
"url": "https://files.pythonhosted.org/packages/c7/c3/b90ced8aa0ccbe12421a7f488ba87898137fdb0c04ca88664b513a9aa83f/eyepop-1.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3ed9a2c473a06b5a67c1bf88cb9e868bfa4f39e51d9496ea81826ebe4ee0b0d6",
"md5": "66758179b779bd706bc04635588f39e6",
"sha256": "dcf2b57592470b39674122eb4f84e9ef9694918a1e1351930a49e8eed6d1c658"
},
"downloads": -1,
"filename": "eyepop-1.6.1.tar.gz",
"has_sig": false,
"md5_digest": "66758179b779bd706bc04635588f39e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 387396,
"upload_time": "2024-12-08T00:56:36",
"upload_time_iso_8601": "2024-12-08T00:56:36.018768Z",
"url": "https://files.pythonhosted.org/packages/3e/d9/a2c473a06b5a67c1bf88cb9e868bfa4f39e51d9496ea81826ebe4ee0b0d6/eyepop-1.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-08 00:56:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eyepop-ai",
"github_project": "eyepop-sdk-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "eyepop"
}
