FramesDepot Class
=================
Overview
--------
The ``FramesDepot`` class is designed to store and manage video frames
in shared memory, allowing for controlled access and efficient frame
management in asynchronous environments. It’s particularly useful in
scenarios where frames need to be shared between different processes or
handled at different rates.
Features
--------
- **Fixed-size Queue**: Holds a specified maximum number of frames.
- **Shared Memory**: Utilizes shared memory for efficient inter-process
communication.
- **Backpressure Management**: Provides a callback mechanism to handle
situations where the frame queue is full.
- **Asynchronous Support**: Designed to work in an asynchronous
environment, ensuring safe and efficient operations.
Usage
-----
Initialization
~~~~~~~~~~~~~~
.. code:: python
frame_size = (width, height, channels) # Dimensions of the frames
memory_name = "frame_depot" # Name for the shared memory block
max_size = 10 # Maximum number of frames in the queue
frames_depot = FramesDepot(frame_size, memory_name, max_size)
Adding Frames
~~~~~~~~~~~~~
.. code:: python
# Assume frame is a NumPy array representing a video frame and current_frame is an integer frame number
frame_dict = {"frame_number": current_frame, "frame": frame}
await frames_depot.enqueue(frame_dict)
Retrieving Frames
~~~~~~~~~~~~~~~~~
.. code:: python
frame_number = 5 # The specific frame number you want to retrieve
frames_depot.get_frame(frame_number)
Handling Full Queue
~~~~~~~~~~~~~~~~~~~
Implement a backpressure_callback function that will be called when the
queue is full.
.. code:: python
def backpressure_callback():
print("The queue is full. Consider slowing down frame production or handling the surplus.")
frames_depot = FramesDepot(frame_size, memory_name, max_size, backpressure_callback)
Clearing the Queue
~~~~~~~~~~~~~~~~~~
.. code:: python
await frames_depot.clear_queue()
Closing and Releasing Resources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code:: python
await frames_depot.close()
Methods
-------
- ``__init__(frame_size, memory_name, max_size, backpressure_callback)``:
Initializes the FramesDepot.
- ``enqueue(frame_dict)``: Asynchronously adds a frame to the queue and
shared memory.
- ``get_frame(frame_number)``: Retrieves a specific frame by number.
- ``clear_queue()``: Asynchronously clears the frame queue and index.
- ``close()``: Asynchronously closes and releases all resources,
including shared memory.
Properties
----------
- ``queue_is_full``: Indicates whether the queue is full.
Requirements
------------
- Python 3.7+
- NumPy
- asyncio
Note
----
Ensure proper synchronization and error handling in your production
environment, especially when dealing with shared resources and
asynchronous operations.
Raw data
{
"_id": null,
"home_page": "https://github.com/m-ghiani/FRAMES_DEPOT",
"name": "gh-frames-depot",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "",
"author": "Massimo Ghiani",
"author_email": "m.ghiani@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/02/43/a0c08b95c82aa6d2033877dbb8f9cbd0519792b54e885ffccd84190b680a/gh-frames-depot-1.0.0.tar.gz",
"platform": null,
"description": "FramesDepot Class\n=================\n\nOverview\n--------\n\nThe ``FramesDepot`` class is designed to store and manage video frames\nin shared memory, allowing for controlled access and efficient frame\nmanagement in asynchronous environments. It\u2019s particularly useful in\nscenarios where frames need to be shared between different processes or\nhandled at different rates.\n\nFeatures\n--------\n\n- **Fixed-size Queue**: Holds a specified maximum number of frames.\n- **Shared Memory**: Utilizes shared memory for efficient inter-process\n communication.\n- **Backpressure Management**: Provides a callback mechanism to handle\n situations where the frame queue is full.\n- **Asynchronous Support**: Designed to work in an asynchronous\n environment, ensuring safe and efficient operations.\n\nUsage\n-----\n\nInitialization\n~~~~~~~~~~~~~~\n\n.. code:: python\n\n frame_size = (width, height, channels) # Dimensions of the frames\n memory_name = \"frame_depot\" # Name for the shared memory block\n max_size = 10 # Maximum number of frames in the queue\n\n frames_depot = FramesDepot(frame_size, memory_name, max_size)\n\nAdding Frames\n~~~~~~~~~~~~~\n\n.. code:: python\n\n # Assume frame is a NumPy array representing a video frame and current_frame is an integer frame number\n frame_dict = {\"frame_number\": current_frame, \"frame\": frame}\n await frames_depot.enqueue(frame_dict)\n\nRetrieving Frames\n~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n frame_number = 5 # The specific frame number you want to retrieve\n frames_depot.get_frame(frame_number)\n\nHandling Full Queue\n~~~~~~~~~~~~~~~~~~~\n\nImplement a backpressure_callback function that will be called when the\nqueue is full.\n\n.. code:: python\n\n def backpressure_callback():\n print(\"The queue is full. Consider slowing down frame production or handling the surplus.\")\n\n frames_depot = FramesDepot(frame_size, memory_name, max_size, backpressure_callback)\n\nClearing the Queue\n~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n await frames_depot.clear_queue()\n\nClosing and Releasing Resources\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n await frames_depot.close()\n\nMethods\n-------\n\n- ``__init__(frame_size, memory_name, max_size, backpressure_callback)``:\n Initializes the FramesDepot.\n- ``enqueue(frame_dict)``: Asynchronously adds a frame to the queue and\n shared memory.\n- ``get_frame(frame_number)``: Retrieves a specific frame by number.\n- ``clear_queue()``: Asynchronously clears the frame queue and index.\n- ``close()``: Asynchronously closes and releases all resources,\n including shared memory.\n\nProperties\n----------\n\n- ``queue_is_full``: Indicates whether the queue is full.\n\nRequirements\n------------\n\n- Python 3.7+\n- NumPy\n- asyncio\n\nNote\n----\n\nEnsure proper synchronization and error handling in your production\nenvironment, especially when dealing with shared resources and\nasynchronous operations.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Package for buffering frames in memory and sharing them between processes.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/m-ghiani/FRAMES_DEPOT"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fd0e73bec25096333c7bbf6a13e5dbb469096cd70009792288b0e278e2bb642e",
"md5": "14d49bbad23b834ee4787358472afb7f",
"sha256": "82ea738e6b73b268922a96403811bb78172afb120d1845100204044c56dee616"
},
"downloads": -1,
"filename": "gh_frames_depot-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "14d49bbad23b834ee4787358472afb7f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 5308,
"upload_time": "2023-12-23T05:05:17",
"upload_time_iso_8601": "2023-12-23T05:05:17.868611Z",
"url": "https://files.pythonhosted.org/packages/fd/0e/73bec25096333c7bbf6a13e5dbb469096cd70009792288b0e278e2bb642e/gh_frames_depot-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0243a0c08b95c82aa6d2033877dbb8f9cbd0519792b54e885ffccd84190b680a",
"md5": "5c2a36569bfd911c4eebfd28aaabf5d0",
"sha256": "1bae639ba23b6a3664fa3d3501a311746917c691ca08494cf2775cd6b977f726"
},
"downloads": -1,
"filename": "gh-frames-depot-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "5c2a36569bfd911c4eebfd28aaabf5d0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 4790,
"upload_time": "2023-12-23T05:05:19",
"upload_time_iso_8601": "2023-12-23T05:05:19.652784Z",
"url": "https://files.pythonhosted.org/packages/02/43/a0c08b95c82aa6d2033877dbb8f9cbd0519792b54e885ffccd84190b680a/gh-frames-depot-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-23 05:05:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "m-ghiani",
"github_project": "FRAMES_DEPOT",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "gh-frames-depot"
}
JSON
