pixel_forge

Module Contents

Classes

Window	Window abstraction for the Windows operating system.
Monitor	Monitor abstraction the Windows operating system.
Capture	Capture class to capture frames from a monitor or a window.

Functions

enumerate_windows(→ list[Window])	Create a list of all windows that are currently available.
foreground_window(→ Window)	Get the current foreground window.
primary_monitor(→ Monitor)	Get the primary monitor.
enumerate_monitors(→ list[Monitor])	Create a list of all monitors.

pixel_forge.enumerate_windows() → list[Window]

Create a list of all windows that are currently available.

Returns:

The list of all windows.

Raises:

RuntimeError – If the window enumeration fails.

pixel_forge.foreground_window() → Window

Get the current foreground window.

Returns:

The foreground window.

Raises:

RuntimeError – No foreground window was found.

class pixel_forge.Window(name: str)

Window abstraction for the Windows operating system.

Windows can be used as capture target for the Capture class.

property valid: bool

True if the window is still valid (i.e., open), else False.

property name: str

The window name.

pixel_forge.primary_monitor() → Monitor

Get the primary monitor.

Returns:

The primary monitor.

pixel_forge.enumerate_monitors() → list[Monitor]

Create a list of all monitors.

Returns:

The list of all monitors.

class pixel_forge.Monitor(id: int | None = None)

Monitor abstraction the Windows operating system.

property width: int

The monitor pixel width.

property height: int

The monitor pixel height.

property index: int

The monitor index.

property refresh_rate: int

The monitor refresh rate in Hz.

property device_name: str

The monitor device name.

property device_string: str

The monitor device string.

class pixel_forge.Capture

Capture class to capture frames from a monitor or a window.

The idea is to get either a Monitor or a Window as target, create a Capture object, and then start a capture thread that will update the internal frame of the Capture object whenever a new frame is available. Frames are only materialized, converted to NumPy arrays and passed over to Python when the user requests it to avoid unnecessary copies.

property active: bool

True if the capture thread is running, False otherwise.

start(capture_target: Monitor | Window, await_first_frame: bool = True) → None

Start the capture.

This registeres an event handler that automatically updates the latest frame whenever a new frame is available. The frame can be accessed using frame(). Since the event handler runs in a separate thread, the first frame might not be available immediately. To ensure a frame is available before continuing, set await_first_frame to True. This will block the main thread until the first frame is available.

Parameters:

• capture_target – The monitor or window to capture.

• await_first_frame – Waits for the first frame to arrive if True.

stop() → None

Stop the capture thread, wait for it to join and invalidate the last frame.

This method is also called automatically when the object is garbage collected.

frame() → numpy.ndarray

Convert the latest frame to an array and return it.

Returns:

The frame as a 3D NumPy array with dimensions [h w 4] (height x width x RGBA).

Raises:

RuntimeError – If the capture thread has not yet picked up a frame.