Add chroma key controls, media pool, FTB enable/disable, fix mask flags

[lucas-romanenko]

Add Chroma Key Sampling & Adjustment Commands

Overview

This PR adds comprehensive support for ATEM chroma key sampling and adjustment features, including new protocol commands, setter methods, state handlers, and state data structures. It also includes fixes for mask and transition flag handling.

New Features

1. Chroma Key Sampling (CACC Protocol)

Added support for controlling the chroma key sampling cursor and preview:

New Setter Methods:

• setKeyChromaSample(mE, keyer, sample) - Enable/disable chroma sample cursor
• setKeyChromaSamplePosition(mE, keyer, x, y) - Set cursor position (normalized 0.0-1.0)
• setKeyChromaSampleSize(mE, keyer, size) - Set cursor size (normalized 0.0-1.0)
• setKeyChromaSamplePreview(mE, keyer, preview) - Enable/disable chroma sample preview

Protocol Support:

• Added CACC command to ATEMProtocol.commands dictionary
• Added KACC status handler to receive chroma sample status updates

State Data:

• Added chroma.sample (bool) - Sample cursor enabled state
• Added chroma.preview (bool) - Preview mode state
• Added chroma.samplePosition (Position object with x, y) - Cursor position
• Added chroma.sampleSize (float) - Cursor size
• Added chroma.sampledColor (dict) - Sampled YCbCr color values with normalized and raw data

2. Chroma Key Adjustments (CACK Protocol)

Added granular control over chroma key adjustment parameters:

New Setter Methods:

• setKeyChromaForeground(mE, keyer, foreground) - Set foreground level (0.0-1.0)
• setKeyChromaBackground(mE, keyer, background) - Set background level (0.0-1.0)
• setKeyChromaKeyEdge(mE, keyer, keyEdge) - Set key edge (0.0-1.0)
• setKeyChromaSpill(mE, keyer, spill) - Set spill suppression (0.0-1.0)
• setKeyChromaFlareSuppression(mE, keyer, flareSuppression) - Set flare suppression (0.0-1.0)
• setKeyChromaBrightness(mE, keyer, brightness) - Set brightness (-1.0 to 1.0)
• setKeyChromaContrast(mE, keyer, contrast) - Set contrast (-1.0 to 1.0)
• setKeyChromaSaturation(mE, keyer, saturation) - Set saturation (0.0 to 2.0)
• setKeyChromaRed(mE, keyer, red) - Set red adjustment (-1.0 to 1.0)
• setKeyChromaGreen(mE, keyer, green) - Set green adjustment (-1.0 to 1.0)
• setKeyChromaBlue(mE, keyer, blue) - Set blue adjustment (-1.0 to 1.0)

Protocol Support:

• Added CACK command to ATEMProtocol.commands dictionary
• Added KACk status handler to receive chroma adjustment status updates
• Implemented _prepareCACKCommandPacket() in ATEMConnectionManager for proper sequence number handling

State Data:

• Added chroma.foreground (float) - Foreground level
• Added chroma.background (float) - Background level
• Added chroma.keyEdge (float) - Key edge parameter
• Added chroma.spill (float) - Spill suppression
• Added chroma.flareSuppression (float) - Flare suppression
• Added chroma.brightness (float) - Brightness adjustment
• Added chroma.contrast (float) - Contrast adjustment
• Added chroma.saturation (float) - Saturation adjustment
• Added chroma.red (float) - Red color adjustment
• Added chroma.green (float) - Green color adjustment
• Added chroma.blue (float) - Blue color adjustment

3. Bug Fixes

Mask/Transition Flags:

• Fixed incorrect flag bit positions in transition and mask setter methods
• Corrected setU8Flag() calls to use proper byte and bit indices
• Examples:
  • Fixed transition style flags (changed from incorrect bit positions)
  • Fixed mask flag handling in keyer methods

Technical Details

Protocol Implementation

• CACC (Chroma Sample Control): 20-byte command packets with mask byte for selective parameter updates
• CACK (Chroma Key Adjustment Command): 28-byte command packets with 16-bit mask for individual parameter control
• Proper handling of signed/unsigned values for color adjustments
• Correct coordinate normalization (X: -16000 to +16000, Y: -9000 to +9000, Size: 620 to 9925)

State Management

• All new state fields properly initialized in StateData/Key.py
• State handlers properly parse and normalize incoming protocol data
• YCbCr color space properly normalized (Y: 0.0-1.0, Cb/Cr: -1.0 to 1.0)

Backward Compatibility

• All new methods are additive - no breaking changes
• Existing chroma key functionality remains unchanged
• New state fields have sensible defaults

Testing

• Tested on ATEM switcher with firmware supporting chroma key sampling and adjustments
• Verified proper mask byte handling for selective parameter updates
• Confirmed correct signed/unsigned value handling for color adjustments
• Validated coordinate normalization and clamping

Files Modified

• ATEMProtocol.py - Added CACC, CACK, KACC, KACk command definitions
• ATEMSetterMethods.py - Added 15 new setter methods for chroma sampling and adjustments
• ATEMCommandHandlers.py - Added _handleKACC() and _handleKACk() handlers
• ATEMConnectionManager.py - Added _prepareCACKCommandPacket() method
• StateData/Key.py - Extended Key.Chroma class with new state fields

Usage Example

from PyATEMMax import ATEMMax

switcher = ATEMMax()
switcher.connect("192.168.1.100")
switcher.waitForConnection()

# Enable chroma sample cursor
switcher.setKeyChromaSample(0, 0, True)

# Set sample cursor position
switcher.setKeyChromaSamplePosition(0, 0, 0.5, 0.5)  # Center

# Set sample cursor size
switcher.setKeyChromaSampleSize(0, 0, 0.1)  # 10% size

# Enable preview
switcher.setKeyChromaSamplePreview(0, 0, True)

# Adjust chroma key parameters
switcher.setKeyChromaForeground(0, 0, 0.5)
switcher.setKeyChromaBackground(0, 0, 0.8)
switcher.setKeyChromaKeyEdge(0, 0, 0.75)
switcher.setKeyChromaSpill(0, 0, 0.6)
switcher.setKeyChromaBrightness(0, 0, 0.1)
switcher.setKeyChromaContrast(0, 0, -0.1)
switcher.setKeyChromaSaturation(0, 0, 1.2)

# Read sampled color
sampled = switcher.key[0][0].chroma.sampledColor
print(f"Sampled Y: {sampled['y']}, Cb: {sampled['cb']}, Cr: {sampled['cr']}")

Related Issues

• Addresses missing chroma key sampling functionality
• Fixes mask/transition flag handling bugs