RGBMatrixEmulator 0.16.4__tar.gz → 0.17.0__tar.gz

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: RGBMatrixEmulator
-Version: 0.16.4
+Version: 0.17.0
 Summary: A PC emulator for Raspberry Pi LED matrices driven by rpi-rgb-led-matrix
 Project-URL: Homepage, https://github.com/ty-porter/RGBMatrixEmulator
 Author-email: Tyler Porter <tyler.b.porter@gmail.com>
@@ -99,6 +99,53 @@ After this, most of the existing command line arguments from the `rpi-rgb-led-ma
 
 Startup of the existing script will be unchanged.
 
+## Multi-Panel Emulation
+
+Emulated multi-panel chaining is supported via `rpi-rgb-led-matrix` CLI flags such as `--led-chain`, `--led-parallel`, `--led-pixel-mappers`. RGBME makes the assumption that the desired orientation for a multi-panel arrangement is a rectangular, upright array of panels.
+
+### `--led-chain` / `--led-parallel`
+
+Single-panel emulation creates an emulated matrix size of `--led-cols` (width) x `--led-rows` (height). For instance, the following command creates a 64x32 emulated matrix.
+
+```sh
+python main.py --led-cols 64 --led-rows 32
+```
+
+`--led-chain` can be thought of as the number of panels chained horizontally, and `--led-parallel` is the number of parallel chains. This also assumes the chains contain the same number of panels. Thus, these flags create a  `--led-cols` x `--led-chain` wide by `--led-rows` x `--led-parallel` high. The following example creates a 128x64 emulated matrix.
+
+```sh
+python main.py --led-cols 64 --led-rows 32 --led-chain 2 --led-parallel 2
+```
+
+### `--led-pixel-mapper`
+
+> [!TIP]  
+> Contributions welcome to support more complex mapper behavior!
+
+RGBME assumes that the user wants to simulate a physical arrangement of panels such that the image appears continuous and upright. This differs a bit from how `rpi-rgb-led-matrix` treats chains and pixel mappers, which describe the wiring arrangement of the panels and the physical arrangement of panels is not specified.
+
+RGBME does **NOT** support pixel mapper chaining:
+
+```sh
+# More than one pixel mapper, V-mapper:Z chained into Rotate:90
+# RGBME will use the first detected mapper.
+python main.py --led-chain 2 --led-parallel 2 --led-pixel-mapper "V-mapper:Z;Rotate:90"
+
+# Valid
+python main.py --led-chain 2 --led-parallel 2 --led-pixel-mapper "V-mapper:Z"
+python main.py --led-chain 2 --led-parallel 2 --led-pixel-mapper "Rotate:90"
+```
+
+Instead, RGBME can use a single pixel mapper to alter the emulated dimensions or perform affine transformations over the entire emulated matrix.
+
+| Mapper | Parameter | Description |
+| --- | --- | --- |
+| `V-mapper` | `Z` (optional) for zig-zag wiring | Folds a horizontal chain into vertical panel stacks. Changes the dimensions to `(W·parallel/chain) × (H·chain/parallel)`.  |
+| `U-mapper` | | Folds a long chain back on itself into a U, halving the width and doubling the height (`W/2 × H·2`). Requires an even chain of at least 2 panels. |
+| `StackToRow` | | Lays parallel chains end-to-end into one wide horizontal row, reshaping the dimensions to `(W·parallel) × (H/parallel)`. |
+| `Rotate` | Angle in degrees, a multiple of 90 (e.g. `90`) | Rotates the displayed image by the given angle. At 90° or 270° the width and height are swapped. |
+| `Mirror` | `H` (default) or `V` | Mirrors the display left/right (`H`) or top/bottom (`V`). Preserves dimensions. |
+
 ## Customization
 
 ### Generating a Configuration File
@@ -228,10 +275,10 @@ Please see the [README for the `browser` display adapter](RGBMatrixEmulator/adap
 
 ### Raspberry Pi 5 Adapter
 
-> [!NOTE]  
-> This adapter is currently experimental.
+> [!WARNING]
+> This adapter is deprecated. It will be removed no later than July 1, 2026. Please use native `rpi-rgb-led-matrix` Raspberry Pi 5 support.
 
-RGBME can be used to "bridge" scripts written for `rpi-rgb-led-matrix` to Raspberry Pi model 5 through [Adafruit Blinka](https://github.com/adafruit/Adafruit_Blinka) and the [Adafruit-Blinka-Raspberry-Pi5-Piomatter](https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter) libraries. As of Jan 1, 2026 `rpi-rgb-led-matrix` does not support Raspberry Pi 5 natively.
+RGBME can be used to "bridge" scripts written for `rpi-rgb-led-matrix` to Raspberry Pi model 5 through [Adafruit Blinka](https://github.com/adafruit/Adafruit_Blinka) and the [Adafruit-Blinka-Raspberry-Pi5-Piomatter](https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter) libraries.
 
 Please see the [README for the `pi5` display adapter](RGBMatrixEmulator/adapters/pi5_adapter/README.md) for further information regarding its configuration and usage.
 
@@ -317,6 +364,7 @@ See [Samples README](samples/README.md) for more information about running examp
     ```
   </details>
 - Drawing large strings is slow, partly because of the `linelimit` parameter in the BDF font parser this emulator uses to prevent multiline text from being rendered unintentionally.
+- `--led-pixel-mapper` emulation differs from `rpi-rgb-led-matrix`. This is due to the assumption made by RGBME for an upright, rectangular emulated matrix. See [Multi-Panel Emulation](#multi-panel-emulation) for details.
 
 ## Contributing
 

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/README.md

@@ -67,6 +67,53 @@ After this, most of the existing command line arguments from the `rpi-rgb-led-ma
 
 Startup of the existing script will be unchanged.
 
+## Multi-Panel Emulation
+
+Emulated multi-panel chaining is supported via `rpi-rgb-led-matrix` CLI flags such as `--led-chain`, `--led-parallel`, `--led-pixel-mappers`. RGBME makes the assumption that the desired orientation for a multi-panel arrangement is a rectangular, upright array of panels.
+
+### `--led-chain` / `--led-parallel`
+
+Single-panel emulation creates an emulated matrix size of `--led-cols` (width) x `--led-rows` (height). For instance, the following command creates a 64x32 emulated matrix.
+
+```sh
+python main.py --led-cols 64 --led-rows 32
+```
+
+`--led-chain` can be thought of as the number of panels chained horizontally, and `--led-parallel` is the number of parallel chains. This also assumes the chains contain the same number of panels. Thus, these flags create a  `--led-cols` x `--led-chain` wide by `--led-rows` x `--led-parallel` high. The following example creates a 128x64 emulated matrix.
+
+```sh
+python main.py --led-cols 64 --led-rows 32 --led-chain 2 --led-parallel 2
+```
+
+### `--led-pixel-mapper`
+
+> [!TIP]  
+> Contributions welcome to support more complex mapper behavior!
+
+RGBME assumes that the user wants to simulate a physical arrangement of panels such that the image appears continuous and upright. This differs a bit from how `rpi-rgb-led-matrix` treats chains and pixel mappers, which describe the wiring arrangement of the panels and the physical arrangement of panels is not specified.
+
+RGBME does **NOT** support pixel mapper chaining:
+
+```sh
+# More than one pixel mapper, V-mapper:Z chained into Rotate:90
+# RGBME will use the first detected mapper.
+python main.py --led-chain 2 --led-parallel 2 --led-pixel-mapper "V-mapper:Z;Rotate:90"
+
+# Valid
+python main.py --led-chain 2 --led-parallel 2 --led-pixel-mapper "V-mapper:Z"
+python main.py --led-chain 2 --led-parallel 2 --led-pixel-mapper "Rotate:90"
+```
+
+Instead, RGBME can use a single pixel mapper to alter the emulated dimensions or perform affine transformations over the entire emulated matrix.
+
+| Mapper | Parameter | Description |
+| --- | --- | --- |
+| `V-mapper` | `Z` (optional) for zig-zag wiring | Folds a horizontal chain into vertical panel stacks. Changes the dimensions to `(W·parallel/chain) × (H·chain/parallel)`.  |
+| `U-mapper` | | Folds a long chain back on itself into a U, halving the width and doubling the height (`W/2 × H·2`). Requires an even chain of at least 2 panels. |
+| `StackToRow` | | Lays parallel chains end-to-end into one wide horizontal row, reshaping the dimensions to `(W·parallel) × (H/parallel)`. |
+| `Rotate` | Angle in degrees, a multiple of 90 (e.g. `90`) | Rotates the displayed image by the given angle. At 90° or 270° the width and height are swapped. |
+| `Mirror` | `H` (default) or `V` | Mirrors the display left/right (`H`) or top/bottom (`V`). Preserves dimensions. |
+
 ## Customization
 
 ### Generating a Configuration File
@@ -196,10 +243,10 @@ Please see the [README for the `browser` display adapter](RGBMatrixEmulator/adap
 
 ### Raspberry Pi 5 Adapter
 
-> [!NOTE]  
-> This adapter is currently experimental.
+> [!WARNING]
+> This adapter is deprecated. It will be removed no later than July 1, 2026. Please use native `rpi-rgb-led-matrix` Raspberry Pi 5 support.
 
-RGBME can be used to "bridge" scripts written for `rpi-rgb-led-matrix` to Raspberry Pi model 5 through [Adafruit Blinka](https://github.com/adafruit/Adafruit_Blinka) and the [Adafruit-Blinka-Raspberry-Pi5-Piomatter](https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter) libraries. As of Jan 1, 2026 `rpi-rgb-led-matrix` does not support Raspberry Pi 5 natively.
+RGBME can be used to "bridge" scripts written for `rpi-rgb-led-matrix` to Raspberry Pi model 5 through [Adafruit Blinka](https://github.com/adafruit/Adafruit_Blinka) and the [Adafruit-Blinka-Raspberry-Pi5-Piomatter](https://github.com/adafruit/Adafruit_Blinka_Raspberry_Pi5_Piomatter) libraries.
 
 Please see the [README for the `pi5` display adapter](RGBMatrixEmulator/adapters/pi5_adapter/README.md) for further information regarding its configuration and usage.
 
@@ -285,6 +332,7 @@ See [Samples README](samples/README.md) for more information about running examp
     ```
   </details>
 - Drawing large strings is slow, partly because of the `linelimit` parameter in the BDF font parser this emulator uses to prevent multiline text from being rendered unintentionally.
+- `--led-pixel-mapper` emulation differs from `rpi-rgb-led-matrix`. This is due to the assumption made by RGBME for an upright, rectangular emulated matrix. See [Multi-Panel Emulation](#multi-panel-emulation) for details.
 
 ## Contributing
 

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/adapters/base.py

@@ -29,7 +29,7 @@ class BaseAdapter:
         self.width = width
         self.height = height
         self.options = options
-        self.__black = Image.new("RGB", self.options.window_size(), "black")
+        self.__black = Image.new("RGB", self.scaled_screen_size, "black")
         self.__mask = self.__draw_mask()
         self.loaded = False
 
@@ -38,6 +38,24 @@ class BaseAdapter:
         self.default_icon_path = (Path(__file__).parent / ".." / "icon.png").resolve()
         self._set_icon_path()
 
+    @property
+    def scaled_screen_size(self):
+        """On-screen size in pixels: the screen (LED grid) scaled by pixel_size."""
+        pixel_size = self.options.pixel_size
+
+        return (self.width * pixel_size, self.height * pixel_size)
+
+    def scaled_screen_size_str(self, pixel_text: str = ""):
+        width, height = self.scaled_screen_size
+
+        return "".join([f"{width} x {height}", pixel_text])
+
+    def screen_size_str(self, pixel_text: str = ""):
+        return "".join([f"{self.width} x {self.height}", pixel_text])
+
+    def panel_size_str(self, pixel_text: str = ""):
+        return "".join([f"{self.options.cols} x {self.options.rows}", pixel_text])
+
     @classmethod
     def get_instance(cls, *args, **kwargs):
         if cls.INSTANCE is None:
@@ -74,7 +92,7 @@ class BaseAdapter:
     #############################################################
     def _get_masked_image(self, pixels):
         image = Image.fromarray(np.array(pixels, dtype=np.uint8), "RGB")
-        image = image.resize(self.options.window_size(), Image.NEAREST)
+        image = image.resize(self.scaled_screen_size, Image.NEAREST)
 
         return Image.composite(image, self.__black, self.__mask)
 
@@ -87,7 +105,7 @@ class BaseAdapter:
         return getattr(self, self.MASK_FNS.get(pixel_style, self.DEFAULT_MASK_FN))
 
     def __draw_mask(self):
-        mask = Image.new("L", self.options.window_size())
+        mask = Image.new("L", self.scaled_screen_size)
 
         draw_fn = self.__mask_fn(self.options.pixel_style)
         draw_fn(mask)
@@ -96,7 +114,7 @@ class BaseAdapter:
 
     def _draw_circle_mask(self, mask):
         pixel_size = self.options.pixel_size
-        width, height = self.options.window_size()
+        width, height = self.scaled_screen_size
 
         drawer = ImageDraw.Draw(mask)
 
@@ -110,7 +128,7 @@ class BaseAdapter:
 
     def _draw_square_mask(self, mask):
         pixel_size = self.options.pixel_size
-        width, height = self.options.window_size()
+        width, height = self.scaled_screen_size
 
         drawer = ImageDraw.Draw(mask)
 
@@ -124,7 +142,7 @@ class BaseAdapter:
 
     def _draw_real_mask(self, mask):
         pixel_size = self.options.pixel_size
-        width, height = self.options.window_size()
+        width, height = self.scaled_screen_size
         pixel_glow = self.options.pixel_glow
 
         if pixel_glow == 0:
@@ -219,8 +237,8 @@ class BaseAdapter:
     def __str__(self):
         return self.DEBUG_TEXT_TEMPLATE.format(
             version.__version__,
-            self.options.cols,
-            self.options.rows,
+            self.width,
+            self.height,
             self.options.chain_length,
             self.options.parallel,
             self.options.pixel_size,

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/adapters/browser_adapter/static/index.html

@@ -26,27 +26,26 @@
                      <tbody>
                         <tr>
                            <td>
-                              Matrix Width:
+                              Panel Size:
                            </td>
                            <td>
-                              {{ adapter.options.cols }}
+                              {{ adapter.panel_size_str(pixel_text="px") }}
                            </td>
                         </tr>
                         <tr>
                            <td>
-                              Matrix Height:
+                              Overall Size:
                            </td>
                            <td>
-                              {{ adapter.options.rows }}
+                              {{ adapter.screen_size_str(pixel_text="px") }}
                            </td>
-                        </td>
                         </tr>
                         <tr>
                            <td>
                               Image Size:
                            </td>
                            <td>
-                              {{ adapter.options.window_size_str(pixel_text="px") }}
+                              {{ adapter.scaled_screen_size_str(pixel_text="px") }}
                            </td>
                         </tr>
                         <tr>

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/adapters/pi5_adapter/__init__.py

@@ -13,6 +13,11 @@ except ImportError:
 
 class Pi5Adapter(BaseAdapter):
     def __init__(self, width, height, options):
+        Logger.warning(
+            "The Pi5 adapter is deprecated. rpi-rgb-led-matrix now provides Raspberry Pi 5 support natively. "
+            "This adapter will be removed no later than July 1, 2026.",
+        )
+
         super().__init__(width, height, options)
         self.matrix = None
         self.framebuffer = None

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/adapters/pygame_adapter.py

@@ -31,7 +31,7 @@ class PygameAdapter(BaseAdapter):
             return
 
         Logger.info(self.emulator_title)
-        self.__surface = pygame.display.set_mode(self.options.window_size())
+        self.__surface = pygame.display.set_mode(self.scaled_screen_size)
         pygame.init()
 
         self.__set_emulator_icon()
@@ -42,7 +42,7 @@ class PygameAdapter(BaseAdapter):
     def draw_to_screen(self, pixels):
         image = self._get_masked_image(pixels)
         pygame_surface = pygame.image.fromstring(
-            image.tobytes(), self.options.window_size(), "RGB"
+            image.tobytes(), self.scaled_screen_size, "RGB"
         )
         self.__surface.blit(pygame_surface, (0, 0))
 

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/adapters/tkinter_adapter.py

@@ -24,12 +24,12 @@ class TkinterAdapter(BaseAdapter):
         self.__set_emulator_icon()
         self.__root.title(self.emulator_title)
 
-        window_size = self.options.window_size()
-        self.__root.geometry("{}x{}".format(*window_size))
+        scaled_screen_size = self.scaled_screen_size
+        self.__root.geometry("{}x{}".format(*scaled_screen_size))
         self.__canvas = tkinter.Canvas(
             self.__root,
-            width=window_size[0],
-            height=window_size[1],
+            width=scaled_screen_size[0],
+            height=scaled_screen_size[1],
             bd=0,
             highlightthickness=0,
             bg="black",

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/adapters/turtle_adapter.py

@@ -29,7 +29,7 @@ class TurtleAdapter(BaseAdapter):
             return
 
         Logger.info(self.emulator_title)
-        turtle.setup(*self.options.window_size())
+        turtle.setup(*self.scaled_screen_size)
         turtle.title(self.emulator_title)
         self.__pen = turtle.Turtle(visible=False)
         self.__screen = self.__pen.getscreen()

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/emulation/canvas.py

@@ -8,15 +8,16 @@ from RGBMatrixEmulator.emulation.options import RGBMatrixOptions
 class Canvas:
     def __init__(self, options: RGBMatrixOptions) -> None:
         self.options = options
+        self.__screen = options.screen
 
-        self.width = options.cols * options.chain_length
-        self.height = options.rows * options.parallel
+        self.width, self.height = self.__screen.pixel_buffer_size
 
         # 3D numpy array -- rows (H), columns (W), 3-tuple RGB
         self.__pdims = (self.height, self.width, 3)
 
+        screen_w, screen_h = self.__screen.screen_size
         self.display_adapter = options.display_adapter.get_instance(
-            self.width, self.height, options
+            screen_w, screen_h, options
         )
 
         self.Clear()
@@ -88,7 +89,7 @@ class Canvas:
 
     # These are delegated to the display adapter to handle specific implementation.
     def draw_to_screen(self) -> None:
-        self.display_adapter.draw_to_screen(self.__pixels)
+        self.display_adapter.draw_to_screen(self.__screen.render(self.__pixels))
 
     def check_for_quit_event(self) -> None:
         self.display_adapter.check_for_quit_event()

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/emulation/matrix.py

@@ -8,8 +8,7 @@ class RGBMatrix:
     def __init__(self, options: RGBMatrixOptions = RGBMatrixOptions()) -> None:
         self.options = options
 
-        self.width = options.cols * options.chain_length
-        self.height = options.rows * options.parallel
+        self.width, self.height = options.screen.pixel_buffer_size
 
     def CreateFrameCanvas(self) -> Canvas:
         self.canvas = Canvas(options=self.options)

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/emulation/options.py

@@ -1,4 +1,5 @@
 from RGBMatrixEmulator.internal.emulator_config import RGBMatrixEmulatorConfig
+from RGBMatrixEmulator.internal.screen import Screen
 
 
 class RGBMatrixOptions:
@@ -14,6 +15,7 @@ class RGBMatrixOptions:
         self.brightness = 100
         self.pwm_lsb_nanoseconds = 130
         self.led_rgb_sequence = "RGB-EMULATED"
+        self.pixel_mapper_config = ""
         self.show_refresh_rate = 0
         self.gpio_slowdown = None
         self.disable_hardware_pulsing = False
@@ -35,13 +37,13 @@ class RGBMatrixOptions:
         # Pi5 Adapter
         self.pi5 = emulator_config.pi5
 
-    def window_size(self) -> tuple[int, int]:
-        return (
-            self.cols * self.pixel_size * self.chain_length,
-            self.rows * self.pixel_size * self.parallel,
-        )
+    @property
+    def screen(self) -> Screen:
+        """The emulated screen model (mapper geometry + render).
 
-    def window_size_str(self, pixel_text: str = "") -> str:
-        width, height = self.window_size()
+        Built lazily and cached, so it snapshots the configured options rather
+        than the defaults present at construction time."""
+        if not hasattr(self, "_screen"):
+            self._screen = Screen(self)
 
-        return f"{width} x {height} {pixel_text}"
+        return self._screen

rgbmatrixemulator-0.17.0/RGBMatrixEmulator/internal/screen.py

@@ -0,0 +1,44 @@
+import numpy as np
+
+from RGBMatrixEmulator.pixel_mappers import get_pixel_mapper
+
+
+class Screen:
+    """
+    The emulated screen: how a program's drawn canvas is mapped into the
+    displayed window.
+
+    It resolves the configured pixel mapper once and snapshots the resulting
+    geometry. The pipeline is:
+
+      pixel_buffer_size  --(LUT)-->  screen_size  --(x pixel_size)-->  scaled
+
+    Both sizes here are in LED units; scaling to on-screen pixels by pixel_size
+    is a rendering concern owned by the display adapter.
+
+      pixel_buffer_size  -- what the program draws into (SetPixel/SetImage),
+                            and the size reported as RGBMatrix.width/height
+      screen_size        -- what the screen shows after the mapper's LUT; a
+                            content transform may change the dimensions (e.g. a 90
+                            degree rotation), so this can differ from the buffer
+    """
+
+    def __init__(self, options) -> None:
+        base_w = options.cols * options.chain_length
+        base_h = options.rows * options.parallel
+
+        mapper = get_pixel_mapper(
+            options.pixel_mapper_config, options.chain_length, options.parallel
+        )
+
+        self.pixel_buffer_size = mapper.get_size_mapping(base_w, base_h)
+        self._lut, self.screen_size = mapper.build_lut(*self.pixel_buffer_size)
+
+    def render(self, pixels: np.ndarray) -> np.ndarray:
+        """Map a pixel buffer to screen pixels via the mapper's LUT."""
+        if self._lut is None:
+            return pixels
+
+        vy_lut, vx_lut = self._lut
+
+        return pixels[vy_lut, vx_lut]

rgbmatrixemulator-0.17.0/RGBMatrixEmulator/pixel_mappers/__init__.py

@@ -0,0 +1,104 @@
+import abc
+
+import numpy as np
+
+"""A gather lookup table: a pair of integer index arrays (vy_lut, vx_lut), each shaped
+like the screen, holding the visible coordinate that feeds each screen pixel.
+Apply with `screen_pixels = visible_pixels[vy_lut, vx_lut]`."""
+LUT = tuple[np.ndarray, np.ndarray]
+
+
+class PixelMapper(abc.ABC):
+    """
+    A pixel mapper, modeled on rpi-rgb-led-matrix's PixelMapper.
+
+    The emulator assumes panels are physically arranged as an upright,
+    rectangular matrix.
+
+    A pixel mapper may:
+    - resize the canvas relative to the base panel grid (V, U, StackToRow)
+    - transform the content the viewer sees within that size (Mirror, Rotate)
+
+    The emulator never drives real LEDs. Mappers describe where pixels
+    end up on screen and not physical panel arrangement.
+    """
+
+    @abc.abstractmethod
+    def get_size_mapping(self, base_w: int, base_h: int) -> tuple[int, int]:
+        """Return the screen (W, H) produced from the base panel grid size."""
+
+    @abc.abstractmethod
+    def map_visible_to_screen(
+        self, draw_w: int, draw_h: int, vx: np.ndarray, vy: np.ndarray
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Map drawn coordinates to displayed-screen coordinates, elementwise.
+
+        `vx` / `vy` are integer arrays of matching shape holding coordinates
+        in the drawn pixel buffer (the `get_size_mapping` size the user draws
+        into). The return is a pair of same-shape arrays holding screen
+        coordinates. `draw_w` / `draw_h` are the drawn-canvas dimensions.
+
+        Arrangement mappers that only resize return their inputs unchanged. A
+        content transform may change the dimensions (e.g. a 90 degree rotation).
+        """
+
+    def build_lut(self, draw_w: int, draw_h: int) -> tuple[LUT | None, tuple[int, int]]:
+        """
+        Compile this mapper's coordinate transform over a pixel buffer of
+        `draw_w` x `draw_h` into a LUT plus the resulting displayed (W, H).
+        """
+        vy_grid, vx_grid = np.indices((draw_h, draw_w))
+        sx, sy = self.map_visible_to_screen(draw_w, draw_h, vx_grid, vy_grid)
+
+        # Identity content transform -> no remapping needed
+        if np.array_equal(sx, vx_grid) and np.array_equal(sy, vy_grid):
+            return None, (draw_w, draw_h)
+
+        display_w = int(sx.max()) + 1
+        display_h = int(sy.max()) + 1
+
+        vx_lut = np.empty((display_h, display_w), dtype=np.intp)
+        vy_lut = np.empty((display_h, display_w), dtype=np.intp)
+        vx_lut[sy, sx] = vx_grid
+        vy_lut[sy, sx] = vy_grid
+
+        return (vy_lut, vx_lut), (display_w, display_h)
+
+
+def get_pixel_mapper(
+    config: str, chain_length: int = 1, parallel: int = 1
+) -> PixelMapper:
+    """
+    Build a single pixel mapper from a config string ("Name" or "Name:param").
+
+    Composition (semicolon-separated chains) is not handled yet; only the first
+    mapper in the string is used.
+    """
+    from RGBMatrixEmulator.pixel_mappers.identity import IdentityMapper
+    from RGBMatrixEmulator.pixel_mappers.mirror import MirrorMapper
+    from RGBMatrixEmulator.pixel_mappers.rotate import RotateMapper
+    from RGBMatrixEmulator.pixel_mappers.stack_to_row import StackToRowMapper
+    from RGBMatrixEmulator.pixel_mappers.umapper import UMapper
+    from RGBMatrixEmulator.pixel_mappers.vmapper import VMapper
+
+    if not config:
+        return IdentityMapper()
+
+    spec = config.split(";")[0].strip()
+    name, _, param = spec.partition(":")
+    key = name.lower().replace("-", "")
+    param = param.strip()
+
+    if key == "mirror":
+        return MirrorMapper(horizontal=(param.upper() != "V"))
+    if key == "rotate":
+        return RotateMapper(angle=int(param) if param else 0)
+    if key == "vmapper":
+        return VMapper(chain_length, parallel, z=(param.upper() == "Z"))
+    if key == "umapper":
+        return UMapper(chain_length, parallel)
+    if key == "stacktorow":
+        return StackToRowMapper(chain_length, parallel)
+
+    return IdentityMapper()

rgbmatrixemulator-0.17.0/RGBMatrixEmulator/pixel_mappers/identity.py

@@ -0,0 +1,15 @@
+import numpy as np
+
+from RGBMatrixEmulator.pixel_mappers import PixelMapper
+
+
+class IdentityMapper(PixelMapper):
+    """No-op mapper. The drawn canvas and the displayed screen are identical."""
+
+    def get_size_mapping(self, base_w: int, base_h: int) -> tuple[int, int]:
+        return (base_w, base_h)
+
+    def map_visible_to_screen(
+        self, screen_w: int, screen_h: int, vx: np.ndarray, vy: np.ndarray
+    ) -> tuple[np.ndarray, np.ndarray]:
+        return (vx, vy)

rgbmatrixemulator-0.17.0/RGBMatrixEmulator/pixel_mappers/mirror.py

@@ -0,0 +1,25 @@
+import numpy as np
+
+from RGBMatrixEmulator.pixel_mappers import PixelMapper
+
+
+class MirrorMapper(PixelMapper):
+    """
+    Mirror the display horizontally (default) or vertically.
+
+    Vectorized port of rpi-rgb-led-matrix's MirrorPixelMapper ("Mirror").
+    Parameter "H" mirrors left/right, "V" mirrors top/bottom. Preserves dimensions.
+    """
+
+    def __init__(self, horizontal: bool = True):
+        self.horizontal = horizontal
+
+    def get_size_mapping(self, base_w: int, base_h: int) -> tuple[int, int]:
+        return (base_w, base_h)
+
+    def map_visible_to_screen(
+        self, screen_w: int, screen_h: int, vx: np.ndarray, vy: np.ndarray
+    ) -> tuple[np.ndarray, np.ndarray]:
+        if self.horizontal:
+            return (screen_w - 1 - vx, vy)
+        return (vx, screen_h - 1 - vy)

rgbmatrixemulator-0.17.0/RGBMatrixEmulator/pixel_mappers/rotate.py

@@ -0,0 +1,35 @@
+import numpy as np
+
+from RGBMatrixEmulator.pixel_mappers import PixelMapper
+
+
+class RotateMapper(PixelMapper):
+    """
+    Rotate the display by a multiple of 90 degrees.
+
+    Based on rpi-rgb-led-matrix's RotatePixelMapper ("Rotate"). With panels in a
+    normal upright arrangement the viewer sees the rotated image. At 90/270 degrees
+    the rotation also swaps the dimensions, so the drawn canvas and the displayed
+    screen have transposed dimensions.
+    """
+
+    def __init__(self, angle: int = 0):
+        if angle % 90 != 0:
+            raise ValueError("Rotate angle must be a multiple of 90 degrees")
+        self.angle = (angle + 360) % 360
+
+    def get_size_mapping(self, base_w: int, base_h: int) -> tuple[int, int]:
+        if self.angle % 180 == 0:
+            return (base_w, base_h)
+        return (base_h, base_w)
+
+    def map_visible_to_screen(
+        self, draw_w: int, draw_h: int, vx: np.ndarray, vy: np.ndarray
+    ) -> tuple[np.ndarray, np.ndarray]:
+        if self.angle == 90:
+            return (draw_h - 1 - vy, vx)
+        if self.angle == 180:
+            return (draw_w - 1 - vx, draw_h - 1 - vy)
+        if self.angle == 270:
+            return (vy, draw_w - 1 - vx)
+        return (vx, vy)

rgbmatrixemulator-0.17.0/RGBMatrixEmulator/pixel_mappers/stack_to_row.py

@@ -0,0 +1,25 @@
+import numpy as np
+
+from RGBMatrixEmulator.pixel_mappers import PixelMapper
+
+
+class StackToRowMapper(PixelMapper):
+    """
+    Lay parallel chains end-to-end as one wide horizontal row.
+
+    Based on rpi-rgb-led-matrix's StackToRowMapper ("StackToRow"). This changes
+    the dimensions of the drawn image but the emulator does not model physical
+    layout, so it is otherwise unchanged.
+    """
+
+    def __init__(self, chain_length: int = 1, parallel: int = 1):
+        self.chain_length = chain_length
+        self.bands = max(parallel, 1)
+
+    def get_size_mapping(self, base_w: int, base_h: int) -> tuple[int, int]:
+        return (base_w * self.bands, base_h // self.bands)
+
+    def map_visible_to_screen(
+        self, screen_w: int, screen_h: int, vx: np.ndarray, vy: np.ndarray
+    ) -> tuple[np.ndarray, np.ndarray]:
+        return (vx, vy)

rgbmatrixemulator-0.17.0/RGBMatrixEmulator/pixel_mappers/umapper.py

@@ -0,0 +1,27 @@
+import numpy as np
+
+from RGBMatrixEmulator.pixel_mappers import PixelMapper
+
+
+class UMapper(PixelMapper):
+    """
+    U-arrangement mapper: a long chain folded back on itself into a U.
+
+    Based on rpi-rgb-led-matrix's UArrangementMapper ("U-mapper"). This changes
+    the dimensions of the drawn image but the emulator does not model physical
+    layout, so it is otherwise unchanged.
+
+    Requires an even chain of at least 2 panels.
+    """
+
+    def __init__(self, chain_length: int = 1, parallel: int = 1):
+        self.chain_length = chain_length
+        self.parallel = parallel
+
+    def get_size_mapping(self, base_w: int, base_h: int) -> tuple[int, int]:
+        return (base_w // 2, base_h * 2)
+
+    def map_visible_to_screen(
+        self, screen_w: int, screen_h: int, vx: np.ndarray, vy: np.ndarray
+    ) -> tuple[np.ndarray, np.ndarray]:
+        return (vx, vy)

rgbmatrixemulator-0.17.0/RGBMatrixEmulator/pixel_mappers/vmapper.py

@@ -0,0 +1,28 @@
+import numpy as np
+
+from RGBMatrixEmulator.pixel_mappers import PixelMapper
+
+
+class VMapper(PixelMapper):
+    """
+    Vertical mapper: a horizontal chain folded into vertical panel stacks.
+
+    Based on rpi-rgb-led-matrix's VerticalMapper ("V-mapper"). This changes
+    the dimensions of the drawn image but the emulator does not model physical
+    layout, so it is otherwise unchanged.
+    """
+
+    def __init__(self, chain_length: int = 1, parallel: int = 1, z: bool = False):
+        self.chain_length = chain_length
+        self.parallel = parallel
+        self.z = z
+
+    def get_size_mapping(self, base_w: int, base_h: int) -> tuple[int, int]:
+        screen_w = base_w * self.parallel // self.chain_length
+        screen_h = base_h * self.chain_length // self.parallel
+        return (screen_w, screen_h)
+
+    def map_visible_to_screen(
+        self, screen_w: int, screen_h: int, vx: np.ndarray, vy: np.ndarray
+    ) -> tuple[np.ndarray, np.ndarray]:
+        return (vx, vy)

{rgbmatrixemulator-0.16.4 → rgbmatrixemulator-0.17.0}/RGBMatrixEmulator/version.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
 
 # package version
-__version__ = "0.16.4"
+__version__ = "0.17.0"
 """Installed version of RGBMatrixEmulator."""