|====================================| | ArtiSCREEN Library Version 1.04 | | Written by: Michel van Osenbruggen | | CopyRight 2026 ArtiLED B.V. | |====================================| Latest change : 28-05-2026 v1.04 changes (28-05-2026) : * Fixed lower_third, lower_two_third, : upper_and_lower_third, upper_and_lower_two_third : so the returned region matches the function name. : No published scene was using the broken behaviour. : * Added top_X / bottom_X aliases for every upper_X / lower_X : so call sites can use either English term. : * Added generic grid(rows, cols) slicer + refactored the : all_parts_* helpers to use it internally (same outputs). : * Added configurable-thickness edge helpers: : top_edge, bottom_edge, left_edge, right_edge. : * Added crop(top, bottom, left, right) and center_crop(fraction). |==========| | Overview | |==========| Library : screen.py Purpose : Screen region extraction for ambilight and video processing Used by : Ambilight mode scripts, video processing pipelines Devices : Hub, Node, Master |=========| | Imports | |=========| import numpy as np : NumPy for array slicing |==============| | Input Format | |==============| Image Array (img_arr) : NumPy array with shape (height, width, 3) — RGB image data : height = rows (vertical axis) : width = cols (horizontal axis) |===================================| | Horizontal (Left/Right) Functions | |===================================| All horizontal functions split the image along the column (width) axis. ---------------------- | left_half(img_arr) | ---------------------- Description : Left half of screen (columns 0 to width/2) Parameters : img_arr — image array Return : left_arr ----------------------- | right_half(img_arr) | ----------------------- Description : Right half of screen (columns width/2 to end) Parameters : img_arr — image array Return : right_arr -------------------------------- | left_and_right_half(img_arr) | -------------------------------- Description : Both halves of screen Parameters : img_arr — image array Return : left_arr, right_arr ----------------------- | left_third(img_arr) | ----------------------- Description : Left third of screen (columns 0 to width/3) Parameters : img_arr — image array Return : left_arr ------------------------ | right_third(img_arr) | ------------------------ Description : Right third of screen (columns 2*width/3 to end) Parameters : img_arr — image array Return : right_arr ------------------------- | center_third(img_arr) | ------------------------- Description : Center third of screen (columns width/3 to 2*width/3) Parameters : img_arr — image array Return : center_arr ------------------------------------ | left_center_right_third(img_arr) | ------------------------------------ Description : All three thirds of screen Parameters : img_arr — image array Return : left_arr, center_arr, right_arr --------------------------------- | left_and_right_third(img_arr) | --------------------------------- Description : Left and right thirds (skipping center) Parameters : img_arr — image array Return : left_arr, right_arr ------------------------------------- | left_and_right_two_third(img_arr) | ------------------------------------- Description : Left 2/3 and right 2/3 (overlapping center) Parameters : img_arr — image array Return : left_arr, right_arr ------------------------- | left_quarter(img_arr) | ------------------------- Description : Left quarter of screen (columns 0 to width/4) Parameters : img_arr — image array Return : left_arr -------------------------- | right_quarter(img_arr) | -------------------------- Description : Right quarter of screen (columns 3*width/4 to end) Parameters : img_arr — image array Return : right_arr -------------------------------- | left_center_quarter(img_arr) | -------------------------------- Description : Left-center quarter (columns width/4 to 2*width/4) Parameters : img_arr — image array Return : left_center_arr --------------------------------- | right_center_quarter(img_arr) | --------------------------------- Description : Right-center quarter (columns 2*width/4 to 3*width/4) Parameters : img_arr — image array Return : right_center_arr ------------------------- | all_quarters(img_arr) | ------------------------- Description : All four quarters of screen Parameters : img_arr — image array Return : left, left_center, right_center, right ----------------------------------- | left_and_right_quarter(img_arr) | ----------------------------------- Description : Left and right quarters (skipping center two) Parameters : img_arr — image array Return : left_arr, right_arr ----------------------- | left_fifth(img_arr) | ----------------------- Description : Left fifth of screen (columns 0 to width/5) Parameters : img_arr — image array Return : left_arr ------------------------- | second_fifth(img_arr) | ------------------------- Description : Second fifth of screen (columns width/5 to 2*width/5) Parameters : img_arr — image array Return : second_arr ------------------------- | center_fifth(img_arr) | ------------------------- Description : Center fifth of screen (columns 2*width/5 to 3*width/5) Parameters : img_arr — image array Return : middle_arr ------------------------- | fourth_fifth(img_arr) | ------------------------- Description : Fourth fifth of screen (columns 3*width/5 to 4*width/5) Parameters : img_arr — image array Return : fourth_arr ------------------------ | right_fifth(img_arr) | ------------------------ Description : Right fifth of screen (columns 4*width/5 to end) Parameters : img_arr — image array Return : right_arr ----------------------- | all_fifths(img_arr) | ----------------------- Description : All five horizontal fifths of screen Parameters : img_arr — image array Return : left, second, center, fourth, right --------------------------------- | left_and_right_fifth(img_arr) | --------------------------------- Description : Left and right fifths (skipping center three) Parameters : img_arr — image array Return : left_fifth, right_fifth |==================================| | Vertical (Upper/Lower) Functions | |==================================| All vertical functions split the image along the row (height) axis. ----------------------- | upper_half(img_arr) | ----------------------- Description : Upper half of screen (rows 0 to height/2) Parameters : img_arr — image array Return : upper_arr ----------------------- | lower_half(img_arr) | ----------------------- Description : Lower half of screen (rows height/2 to end) Parameters : img_arr — image array Return : lower_arr --------------------------------- | upper_and_lower_half(img_arr) | --------------------------------- Description : Both halves of screen Parameters : img_arr — image array Return : upper_arr, lower_arr ------------------------ | upper_third(img_arr) | ------------------------ Description : Upper third of screen (rows 0 to height/3) Parameters : img_arr — image array Return : upper_arr ------------------------ | lower_third(img_arr) | ------------------------ Description : Lower third of screen (rows 2*height/3 to end) — v1.04 fix Parameters : img_arr — image array Return : lower_arr ---------------------------- | upper_two_third(img_arr) | ---------------------------- Description : Upper two-thirds of screen (rows 0 to 2*height/3) Parameters : img_arr — image array Return : upper_arr ---------------------------- | lower_two_third(img_arr) | ---------------------------- Description : Lower two-thirds of screen (rows height/3 to end) — v1.04 fix Parameters : img_arr — image array Return : lower_arr ---------------------------------- | upper_and_lower_third(img_arr) | ---------------------------------- Description : Upper third + lower third (both 1/3 bands) — v1.04 fix Parameters : img_arr — image array Return : upper_arr, lower_arr -------------------------------------- | upper_and_lower_two_third(img_arr) | -------------------------------------- Description : Upper two-thirds + lower two-thirds (overlapping 2/3 bands) — v1.04 fix Parameters : img_arr — image array Return : upper_arr, lower_arr ------------------------------------- | upper_middle_lower_third(img_arr) | ------------------------------------- Description : All three vertical thirds Parameters : img_arr — image array Return : upper_arr, middle_arr, lower_arr -------------------------- | upper_quarter(img_arr) | -------------------------- Description : Upper quarter of screen (rows 0 to height/4) Parameters : img_arr — image array Return : upper_arr -------------------------- | lower_quarter(img_arr) | -------------------------- Description : Lower quarter of screen (rows 3*height/4 to end) Parameters : img_arr — image array Return : lower_arr --------------------------------- | upper_middle_quarter(img_arr) | --------------------------------- Description : Upper-middle quarter (rows height/4 to 2*height/4) Parameters : img_arr — image array Return : upper_middle_arr --------------------------------- | lower_middle_quarter(img_arr) | --------------------------------- Description : Lower-middle quarter (rows 2*height/4 to 3*height/4) Parameters : img_arr — image array Return : lower_middle_arr ------------------------------------ | upper_and_lower_quarter(img_arr) | ------------------------------------ Description : Upper and lower quarters (skipping center two) Parameters : img_arr — image array Return : upper_arr, lower_arr ------------------------ | upper_fifth(img_arr) | ------------------------ Description : Upper fifth of screen (rows 0 to height/5) Parameters : img_arr — image array Return : upper_arr ------------------------------- | upper_second_fifth(img_arr) | ------------------------------- Description : Second fifth of screen (rows height/5 to 2*height/5) Parameters : img_arr — image array Return : upper_second_arr ------------------------- | middle_fifth(img_arr) | ------------------------- Description : Middle fifth of screen (rows 2*height/5 to 3*height/5) Parameters : img_arr — image array Return : middle_arr ------------------------------- | lower_fourth_fifth(img_arr) | ------------------------------- Description : Fourth fifth of screen (rows 3*height/5 to 4*height/5) Parameters : img_arr — image array Return : lower_fourth_arr ------------------------ | lower_fifth(img_arr) | ------------------------ Description : Lower fifth of screen (rows 4*height/5 to end) Parameters : img_arr — image array Return : lower_arr ---------------------------------- | upper_and_lower_fifth(img_arr) | ---------------------------------- Description : Upper and lower fifths (skipping center three) Parameters : img_arr — image array Return : upper_arr, lower_arr -------------------------------- | all_vertical_fifths(img_arr) | -------------------------------- Description : All five vertical fifths of screen Parameters : img_arr — image array Return : upper, second, middle, fourth, lower |============================| | Grid (All Parts) Functions | |============================| Grid functions split the image along both axes, returning a 2D grid of regions. Return order is row-major: left to right, top to bottom. --------------------------- | all_parts_half(img_arr) | --------------------------- Description : Split into 2x2 grid (4 parts) Parameters : img_arr — image array Return : upper_left, upper_right, lower_left, lower_right ----------------------------- | all_parts_thirds(img_arr) | ----------------------------- Description : Split into 3x3 grid (9 parts) Parameters : img_arr — image array Return : upper_left, upper_center, upper_right, middle_left, middle_center, middle_right, lower_left, lower_center, lower_right ------------------------------- | all_parts_quarters(img_arr) | ------------------------------- Description : Split into 4x4 grid (16 parts) Parameters : img_arr — image array Return : 16 regions: upper to bottom, left to right ----------------------------- | all_parts_fifths(img_arr) | ----------------------------- Description : Split into 5x5 grid (25 parts) Parameters : img_arr — image array Return : 25 regions: upper to bottom, left to right ---------------------------------- | grid(img_arr, n_rows, n_cols) | ---------------------------------- Description : Generic grid slicer — split into n_rows x n_cols equal regions Parameters : img_arr — image array : n_rows — number of vertical splits : n_cols — number of horizontal splits Return : 2D list (list of row-lists) of sub-arrays Notes : all_parts_half/thirds/quarters/fifths now use this internally. |=================| | Edge / Crop | |=================| Configurable-thickness edge slicers and generic crop helpers — handy for ambilight bands the fraction-based split functions can't express directly. ------------------------------------ | top_edge(img_arr, thickness) | ------------------------------------ Description : Top `thickness` rows of the image Parameters : img_arr — image array : thickness — number of rows (clamped to image height) Return : sub-array of shape (thickness, width, 3) ------------------------------------ | bottom_edge(img_arr, thickness) | ------------------------------------ Description : Bottom `thickness` rows of the image Parameters : img_arr — image array : thickness — number of rows Return : sub-array of shape (thickness, width, 3) ----------------------------------- | left_edge(img_arr, thickness) | ----------------------------------- Description : Leftmost `thickness` columns of the image Parameters : img_arr — image array : thickness — number of columns Return : sub-array of shape (height, thickness, 3) ------------------------------------ | right_edge(img_arr, thickness) | ------------------------------------ Description : Rightmost `thickness` columns of the image Parameters : img_arr — image array : thickness — number of columns Return : sub-array of shape (height, thickness, 3) ---------------------------------------------------------- | crop(img_arr, top=0, bottom=0, left=0, right=0) | ---------------------------------------------------------- Description : Letterbox crop — remove pixels from each edge Parameters : img_arr — image array : top — pixels to crop from the top : bottom — pixels to crop from the bottom : left — pixels to crop from the left : right — pixels to crop from the right Return : cropped sub-array ---------------------------------------- | center_crop(img_arr, fraction) | ---------------------------------------- Description : Keep the central `fraction` of width AND height Parameters : img_arr — image array : fraction — 0.0..1.0 (e.g. 0.5 keeps the middle 50% in each : dimension = 25% of total area) Return : centred sub-array |=================| | top / bottom | | aliases | |=================| Every `upper_X` function has a `top_X` alias and every `lower_X` function has a `bottom_X` alias — pure aliases (no behaviour difference) added in v1.04 so call sites can use whichever English term reads better. Examples: top_half = upper_half top_third = upper_third top_two_third = upper_two_third top_quarter = upper_quarter top_middle_quarter = upper_middle_quarter top_fifth = upper_fifth top_second_fifth = upper_second_fifth top_and_bottom_half = upper_and_lower_half top_and_bottom_third = upper_and_lower_third top_and_bottom_two_third = upper_and_lower_two_third top_and_bottom_quarter = upper_and_lower_quarter top_and_bottom_fifth = upper_and_lower_fifth top_middle_bottom_third = upper_middle_lower_third bottom_half = lower_half bottom_third = lower_third (FIXED in v1.04 — actual lower 1/3) bottom_two_third = lower_two_third (FIXED in v1.04 — actual lower 2/3) bottom_quarter = lower_quarter bottom_middle_quarter = lower_middle_quarter bottom_fourth_fifth = lower_fourth_fifth bottom_fifth = lower_fifth |================| | Flip Functions | |================| Flip functions mirror the image along one or both axes. ------------------- | flip_x(img_arr) | ------------------- Description : Flip image horizontally (mirror left/right) Parameters : img_arr — image array Return : flipped img_arr ------------------- | flip_y(img_arr) | ------------------- Description : Flip image vertically (mirror top/bottom) Parameters : img_arr — image array Return : flipped img_arr -------------------- | flip_xy(img_arr) | -------------------- Description : Flip image both horizontally and vertically (180° rotation) Parameters : img_arr — image array Return : flipped img_arr