Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

🎉 feat(PiGear): Added official support for new Picamera2 API (Fixes #342) #392

Merged
merged 15 commits into from
May 13, 2024

Conversation

abhiTronix
Copy link
Owner

@abhiTronix abhiTronix commented Apr 9, 2024

Brief Description

This PR brings exciting new features to PiGear! We've added official support for the powerful Picamera2 API, unlocking a world of possibilities for Raspberry Pi Camera Modules and limited USB camera functionality.

✨Key PiGear Enhancements include:

  • Seamless Python wrapper: A robust wrapper around Picamera2 API library simplifies integration with minimal code changes for existing PiGear users.
  • Enhanced camera control: Leverages libcamera API under the hood for Raspberry Pi Camera Modules.
  • Existing compatibility: Maintains compatibility with PiGear's existing super-charged multi-threaded and colorspace manipulation framework.
  • Proper Resource management: Ensures proper resource release during PiGear termination.
  • USB camera support (limited): Provides basic functionality for USB webcams. PiGear could accurately differentiates between USB and Raspberry Pi cameras using metadata.
  • Backward compatibility: Seamlessly switches to the legacy Picamera library backend if Picamera2 is unavailable.
  • Standalone functionalities: Standalone functionalities for both legacy picamera and newer picamera2 backends for clarity.
  • Document Overhaul: *
  • Advanced optional parameters handling: Handles camera configurational parameters and user-defined settings for various camera types.
    • New optional configurationalparameters: Currently Supports "sensor", "format", "controls", "transform", "stride", "buffer_count", and "queue" with sanity checks. Seperated Raspberry Pi camera module exclusive and Unified USB cameras supported optional parameters.
    • New user-defined optional parameters: Such as auto_align_output_config, enable_verbose_logs, and more.
  • Additional changes:
    • Logging optimization with warning for common libcamera messages
    • Lowered framerate minimum value to 0.0.
    • Moved sensor optional parameter to commonly supported picamera2 configurational parameters.
    • Removed unsupported bit_depth optional parameters
    • Updated PiGear API tagline and introduction
    • Fixed colorspace typo bug
    • Fixed UnboundLocalError bug for 'picamera2' variable assigment.
    • Fixed UnboundLocalError bug for 'queue' variable assignment.

📝 Documentation updates:

  • Added a warning advising users to disable common libcamera messages when logging is disabled.
  • Updated Zenodo badge and BibTeX entry
  • Added complete Picamera2 library installation instructions for pip and from source as a dependency.
  • Updated Picamera2 installation instructions (including apt, pip, pre-installation on Raspberry Pi images, and compatibility warnings)
  • Moved legacy Picamera library installation instructions to an admonition.
  • Removed Importing section from overview to avoid confusion in PiGear.
  • Overhauled mkdocs theme.
    • Added unrecognized_links: ignore to mkdocs.yml for validations.
    • Added new features to mkdocs.yml
      • Added custom admonition icons to mkdocs.yml
      • Migrated to new Google Analytics 4 in mkdocs.yml
      • Added new git-authors plugin in mkdocs.yml
      • Added new tables markdown extension
      • Added custom fences to pymdownx.superfences markdown extension
      • Added line_spans: __span and pygments_lang_class: true parameters to pymdownx.highlight markdown extension
      • Added normalize_issue_symbols: true to pymdownx.magiclink markdown extension
      • Added new mkdocs feature dependency mkdocs-git-authors-plugin
      • Replaced depreciated materialx with supported emoji extension.
      • Replaced permalink icon with default one
  • Added missing version contributors to changelog.md
  • Added new icons to make headings more readable
  • Replaced unsupported admonitions with supported ones
  • Removed all custom admonition icons and color CSS from custom.css
  • Removed Twitter section from help and docs site metadata
  • Fixed Ko-fi sponsorship heart hover effect in footer
    • Replaced twemoji heart emoji with heart-pulse fontawesome SVG
  • Fixed titles and indentations in various admonitions.
  • Removed Gitter community chat sidecard JS file.
  • Redefined spacing between sections
  • Fixed various typos, code comments, and hyperlinks URLs.

🧑‍💻 Maintenance Updates:

  • Moved logging enablement before version logging for consistency in vidgear APIs.
  • Removed redundant boolean assignment for various APIs internal logging.
  • Simplified conditional statements and assignments using short-circuiting, Boolean operations, and ternary operators.
  • Refactored return data handling in netgear_async.py
  • Refactored vidgear code to improve readability, maintainability, and performance
  • Added .cache directory to .gitignore
  • Updated vidgear library version to v0.3.3
  • Dropped legacy picamera dependency in Setup.py
  • Improved code efficiency with short-circuiting and formatting
  • Updated logging practices to be more developer-friendly
  • Added patch for substring index bug in get_supported_demuxers helper method.
  • Updated code comments

👷CI Updates:

  • Temporarily removed PiGear API from code coverage due to hardware limitations

Requirements / Checklist

Related Issue

#342

Context

This update significantly enhances PiGear's camera capabilities with newer libcamera based Picamer2 API while maintaining backward compatibility and improving code structure.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

✨ This update brings official support for the new Picamera2 API, unlocking powerful features for Raspberry Pi Camera Modules and limited USB camera support.

Key improvements:
- 🚸 Seamless Python wrapper: A robust wrapper around Picamera2 API library simplifies integration with minimal code changes for existing PiGear users.
- ⚡️ Enhanced camera control: Leverages libcamera API under the hood for Raspberry Pi Camera Modules.
- ⚡️ Existing compatibility: Maintains compatibility with PiGear's existing super-charged multi-threaded and colorspace manipulation framework.
- ⚡️ Resource management: Ensures proper resource release during PiGear termination.
- ✨ USB camera support (limited): Provides basic functionality for USB webcams. PiGear could accurately differentiates between USB and Raspberry Pi cameras using metadata.
- 🧑‍💻 Backward compatibility: Seamlessly switches to the legacy PiCamera library if Picamera2 is unavailable.
- 🧑‍💻 Standalone functionalities: Separates functionalities for both legacy and newer APIs for clarity.
- ⚡️ Automatic configuration management: Handles common configuration parameters and non-standard settings for various camera types.
- New internal parameters:
  - 🚩 auto_align_output_config: Optimizes output frame configuration for the camera sensor.
  - 🚩 enable_verbose_logs: Enables more detailed logging through Picamera2.
- Unified `format` parameter:
  - 🥅 Defaults to RGB888 (24-bit BGR) for Raspberry Pi cameras.
  - 🦺 Validates formats for USB cameras before handling.
  - 🥅 Requires explicit `colorspace` definition if `format` is not MPEG (USB cameras) or for specific formats in Raspberry Pi cameras.
- Raspberry Pi camera exclusive parameters:
  - 🚩 Currently Supports `"controls," "queue," "transform," "bit_depth," "buffer_count," "sensor," and "stride"` with type checks.
- ⚡️ Framerate handling: Tailored framerate handling based on camera type.
- 🦺 Logging optimization: Added a warning advising users to disable common libcamera messages when logging is disabled.

Additional Changes:
- 💥 Dropped legacy `picamera` dependency in `Setup.py`.
- 💡 Improved code efficiency with short-circuiting and formatting.
- 🔊 Updated logging practices.

CI:
- 🏗️ Temporarily removed PiGear API from code coverage due to hardware limitations.
@abhiTronix abhiTronix added ENHANCEMENT ⚡ New Feature/Addition/Improvement WORK IN PROGRESS 🚧 currently been worked on. PROPOSAL 📩 A proposal/proposition DOCS 📜 Issue/PR is related to vidgear docs. PENDING TESTS 🧪 Waiting for CI tests to complete successfully. labels Apr 9, 2024
@abhiTronix abhiTronix added this to the v0.3.3 milestone Apr 9, 2024
@abhiTronix abhiTronix self-assigned this Apr 9, 2024
@abhiTronix abhiTronix changed the title 🎉 feat(PiGear): Add official support for new Picamera2 API (Fixes #342) 🎉 feat(PiGear): Added official support for new Picamera2 API (Fixes #342) Apr 9, 2024
@abhiTronix abhiTronix linked an issue Apr 9, 2024 that may be closed by this pull request
4 tasks
Copy link

codecov bot commented Apr 9, 2024

Codecov Report

Attention: Patch coverage is 95.23810% with 2 lines in your changes are missing coverage. Please review.

Project coverage is 93.56%. Comparing base (4497fbb) to head (7770489).
Report is 1 commits behind head on testing.

Files Patch % Lines
vidgear/gears/asyncio/netgear_async.py 85.71% 2 Missing ⚠️
Additional details and impacted files
@@             Coverage Diff             @@
##           testing     #392      +/-   ##
===========================================
- Coverage    93.90%   93.56%   -0.35%     
===========================================
  Files           16       15       -1     
  Lines         3169     3013     -156     
===========================================
- Hits          2976     2819     -157     
- Misses         193      194       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

- 🧑‍💻 Replaced legacy Picamera library installation instructions with Picamera2 python library.
- 📝 Added two methods of Picamera2 installation: using `apt`(recommended) and using `pip`.
- 🚸 Added information admonition about Picamera2 comes pre-installed on images downloaded from Raspberry Pi.
- 🚸 Added warning admonition Picamera2 is only supported on Raspberry Pi OS Bullseye (or later) images.
- 🚸 Moved legacy Picamera library optional installation instructions to a Admonition.
- 🔇 Added `unrecognized_links: ignore` to mkdocs.yml for validations to minimize logging.
- 📝 Updated vidgear library binaries version.
- 📝 Added new `navigation.tabs.sticky`, `navigation.tracking`, `navigation.instant`, and `navigation.instant.progress` features.
- 📱 Replaced docs font `Muli` with `Source Sans 3`.
- 💄 Added custom admonition icons to `mkdocs.yml`.
- 🚩 Added `enable_creation_date:true` and `fallback_to_build_date: true` to `git-revision-date-localized` plugin.
- 🚚 Migrated to new Google Analytics 4 in mkdocs.yml.
- ✨ Added new `git-authors` plugin in `mkdocs.yml`.
- ✨ Added new `tables` markdown extension.
- 🚩 Added `custom_fences` to `pymdownx.superfences` markdown extension.
- 🚩 Added `line_spans: __span` and `pygments_lang_class: true` parameters to `pymdownx.highlight` markdown extension.
- 🚩 Added `normalize_issue_symbols: true` to `pymdownx.magiclink` markdown extension.
- ✨ Added complete Picamera2 library installation instructions for pip and source.
  - 🚚 Moved legacy picamera python library installation instructions to admonition.
- ➕ Added new mkdocs feature dependency `mkdocs-git-authors-plugin`.
- 👥 Added missing version contributors to changelog.md
- 🧑‍💻 Added new icons to make headings more readable.
- 🗑️ Replace depreciated `materialx` with supported `extensions` emoji extension.
- 🩹 Fixed titles and indentations in various admonitions.
- 📝 Replaced permalink icon with default one.
- 🩹 Replaced wrong unsupported admonitions with supported ones.
- 🔥 Removed all custom admonition icons and color CSS from `custom.css`.
- 🙈 Added `.cache` directory to `.gitignore`.
- 🔥 Removed Twitter section from help and site metadata.
- 🩹 Fixed Ko-fi sponsorship heart hover effect in footer.
- 💄 Replace twemoji `heart` with `heart-pulse` fontawesome SVG.
- 🔥 Removed Gitter community chat sidecard js.
- 💄 Redefined spacing between sections.
- ✏️ Fixed small typos and hyperlinks.
- 🚩 Moved `sensor` optional parameter to common supported picamera2 config parameters.
- 🔥 Removed unsupported `bit_depth`, `buffer_count`, `queue` optional parameter from picamera2 config parameters.
- 🥅 Added sanity checks for `sensor` optional parameter, only `output_size`, `bit_depth` config parameters are supported.
- 🥅 Added sanity checks for `controls` optional parameter, only camera sensor specific config parameters extracted using `camera.camera_controls` are supported.
- 💡 Added comments related to `controls`, `transform` and `stride` not supported with USB cameras.
- 🔊 Updated logs to be more developer friendly.
- 📝 Added a concise tagline of the PiGear API. Emphasize its seamless wrapper around Picamera2, compatibility with various camera modules, and robust resource management through the Threaded Internal Timer feature.
- 🧑‍💻 Update the PiGear API introduction in the documentation to provide a more concise and intuitive summary. Highlight the key features, such as seamless Picamera2 integration, enhanced camera control, USB camera support, and automatic configuration management.
- ♿️ Reflected these updated changes in `README.md` and `index.md`, and PiGear source code comments.
- 🩹 Fixed colorspace typo bug in PiGear API.
- 💡 Fixed minor code comments.
…ation

- **Overview**
    - 📝 Updated the description for the camera module and added limited USB camera support with the `Picamera2` backend.
    - 🧑‍💻  Added backward compatibility information for seamless legacy `Picamera` switching.
- **Parameters**
    - 🚸 Clarified the `camera_num` parameter to allow multiple cameras.
    - 📝 Updated the `options` parameter with new sections:
        - Configurational Camera Parameters (provided by the backend library).
        - User-defined Parameters (e.g., `enforce_legacy_picamera`, `enable_verbose_logs`).
    - 🧑‍💻 Updated admonitions, examples, and text for each parameter.
- **Usage Examples**
    - 📝 Updated examples for Picamera2 configuration, user-defined parameters, and legacy Picamera usage.
    - ✨ Added new admonitions on:
        - Picamera2 configurational parameters (with table) and library installation.
        - Enabling verbose logs for the Picamera2 backend.
        - Limited USB camera support with the Picamera2 backend.
        - Prioritization of the Picamera2 backend and enforcing the legacy backend.
        - Disabling common `libcamera` messages in silent mode.
    - 📝 Updated the usage example to include examples for both the `picamera2` and legacy `picamera` backends when using the PiGear API.
- **Bonus Examples**
    - ✨ Added examples for changing the output pixel format and accessing multiple cameras (Picamera2 backend).
    - ✨ Added new example for dynamically adjusting Raspberry Pi Camera Parameters at Runtime in the PiGear API for both the `picamera2` and legacy `picamera` backends.
- **FAQ**
    - 📝 Updated answers to refer to the "Switching from OpenCV" guide and API documentation.
    - ✨ Added new questions and answers related to PiGear API features.
- 📝 Updated the PiGear description to include support for camera modules and limited USB cameras on Raspberry Pis.
- ✨ Added a note about enforcing the legacy Picamera API backend using the `enforce_legacy_picamera` parameter in various documents concerning the PiGear API.
- 🚸Updated formatting and readability in various documentation files.
- 🧑‍💻 Updated the warning message about enabling Raspberry Pi camera hardware-specific settings.
- 💄Added `content.footnote.tooltips` feature in `mkdocs.yml`.

- 🏗️Moved logging enablement before version logging for consistency.
- 🔥Removed redundant boolean assignment for `self.__logging`.
- 🧑‍💻 Simplified conditional statements and assignments using short-circuiting, Boolean operations, and ternary operators.
- ♻️ In `netgear_async.py`: Refactored return data handling in `recv_generator`.
- ♻️ vidgear code has been refactored to improve readability, maintainability, and performance.
- 🧑‍💻 Renamed references from 'PiCamera2' to 'picamera2' for consistency
- 🚩 Added option to enforce legacy picamera API with 'enforce_legacy_picamera' optional boolean parameter.
- ⚡️Improved logging and warning messages for unsupported/custom formats.
- ✨ Added `buffer_count` and `queue` configuration parameter options for picamera2 API.
- 🏗️ Renamed `auto_align_output_config` to `auto_align_output_size`.
- 🔊 Included `buffer_count` and `queue` in `picamera2` parameter logging.
- ✏️ Fixed a typo in the error message for Camera Module API failure.
- 💡 Clarified comments for thread joining during `stop()`.
- 🚸 Minor code formatting and comment updates.
…ted_demuxers` method.

Docs:
- 📝 Updated the PiGear API's example to new Picamera2 backend in README.md.
- 🚀 Applied new Picamera2 backend integration documentation changes to StreamGear, plus VideoGear and its dependent WebGear, WebGear_RTC, and NetGear_Async API's Parameters, Usage and Bonus examples.
- ✏️ Fixed typos typos and context in documentation.
- ✏️ Fixed typos in hyperlink URLs.
@abhiTronix abhiTronix merged commit e119365 into testing May 13, 2024
11 checks passed
@abhiTronix abhiTronix deleted the development branch May 13, 2024 17:59
@abhiTronix abhiTronix removed the WORK IN PROGRESS 🚧 currently been worked on. label May 13, 2024
@abhiTronix abhiTronix added the SOLVED 🏁 This issue/PR is resolved now. Goal Achieved! label May 13, 2024
@abhiTronix abhiTronix removed the PENDING TESTS 🧪 Waiting for CI tests to complete successfully. label Jun 19, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
DOCS 📜 Issue/PR is related to vidgear docs. ENHANCEMENT ⚡ New Feature/Addition/Improvement PROPOSAL 📩 A proposal/proposition SOLVED 🏁 This issue/PR is resolved now. Goal Achieved!
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Proposal]: Support Picamera2
1 participant