-
Notifications
You must be signed in to change notification settings - Fork 8
Description
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
-
Enum class: Using Python's
enum.Enuminstead of a static class would provide even stronger type safety, but might be overkill and less flexible for incremental additions. -
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. -
Documentation only: Simply documenting supported formats better wouldn't solve the core problem of typos and inconsistencies in the codebase.
-
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.