Skip to content

Replace hardcoded pixel format strings with static class constants #95

@GaijinKa

Description

@GaijinKa

Is your feature request related to a problem? Please describe.

Working with raw pixel format strings like 'rgb24', 'bgr24', 'yuv420p', etc. throughout the codebase makes the code error-prone because:

  • Typos in format strings (e.g., 'rgb' vs 'rgb24') can cause silent failures or runtime errors
  • There's no IDE autocomplete support for available formats
  • It's unclear which formats are officially supported/tested vs. which are untested FFmpeg formats
  • Different developers might use inconsistent naming for the same encoding
  • Refactoring becomes difficult when format strings are scattered throughout the code

Describe the solution you'd like

Replace all hardcoded pixel format strings with a static class containing predefined constants. For example:

class PixelFormat:
    # RGB/BGR formats (24-bit)
    RGB24 = 'rgb24'
    BGR24 = 'bgr24'
    
    # RGBA formats (32-bit with alpha)
    RGBA = 'rgba'
    ARGB = 'argb'
    BGRA = 'bgra'
    ABGR = 'abgr'
    
    # YUV formats
    YUV420P = 'yuv420p'
    YUV444P = 'yuv444p'
    YUYV422 = 'yuyv422'
    
    # Grayscale
    GRAY = 'gray'
    GRAY8 = 'gray8'
    
    # Other
    PAL8 = 'pal8'
    GBRP = 'gbrp'

Usage would then become:

frame.to_ndarray(format=PixelFormat.RGB24)  # instead of format='rgb24'

This approach provides several benefits:

  • Type safety: IDE autocompletion and type checking
  • Fine-grained control: Only officially supported/tested formats are exposed
  • Incremental support: New formats can be added gradually as they're tested
  • Maintainability: Centralized definition makes it easy to see all supported formats
  • Discoverability: Developers can easily browse available formats via IDE suggestions
  • Flexibility: Developers can still rely on their own format if they are working in isolated mode

Describe alternatives you've considered

  1. Enum class: Using Python's enum.Enum instead of a static class would provide even stronger type safety, but might be overkill and less flexible for incremental additions.

  2. String literals with type hints: Using Literal['rgb24', 'bgr24', ...] type hints would catch errors at type-check time but wouldn't prevent runtime issues or provide autocomplete in all contexts.

  3. Documentation only: Simply documenting supported formats better wouldn't solve the core problem of typos and inconsistencies in the codebase.

  4. Module-level constants: Defining RGB24 = 'rgb24' at module level would work but lacks the organization and discoverability of a dedicated class.

Additional context

This change would be backward compatible since the underlying values remain the same strings. Existing code using raw strings would continue to work, allowing for gradual migration. The class could also include helper methods like PixelFormat.is_rgb(), PixelFormat.has_alpha(), etc. for common format checks.

This pattern is commonly used in well-maintained libraries (e.g., http.HTTPStatus, logging level constants) and significantly improves developer experience and code quality.

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions