895class SegmentedTable(TableIndexer):
 896    """
 897    Represents a detected table grid as a 2D array of intersection points.
 898
 899    Returned by `Taulu.segment_table`. Provides methods for querying cell
 900    locations, cropping cells/regions from the source image, and interactive
 901    visualization. Can be saved to and restored from JSON.
 902    """
 903
 904    _right_offset: int | None = None
 905
 906    def __init__(self, points: list[list[Point]], right_offset: int | None = None):
 907        """
 908        Args:
 909            points: 2D list of intersections between horizontal and vertical
 910                rules, in row-major order.
 911            right_offset: For tables built from a `Split`, the column index
 912                where the right half begins. ``None`` for single-page tables.
 913        """
 914        self._points = points
 915        self._right_offset = right_offset
 916
 917    @property
 918    def points(self) -> list[list[Point]]:
 919        """The raw 2D grid of intersection points."""
 920        return self._points
 921
 922    def row(self, i: int) -> list[Point]:
 923        """Return the ``i``-th row of intersection points."""
 924        assert 0 <= i and i < len(self._points)
 925        return self._points[i]
 926
 927    @property
 928    def cols(self) -> int:
 929        """Number of cell columns (one fewer than vertical rules; two fewer
 930        for split tables, accounting for the seam between halves)."""
 931        if self._right_offset is not None:
 932            return len(self.row(0)) - 2
 933        else:
 934            return len(self.row(0)) - 1
 935
 936    @property
 937    def rows(self) -> int:
 938        """Number of cell rows (one fewer than horizontal rules)."""
 939        return len(self._points) - 1
 940
 941    @property
 942    def right_offset(self) -> int | None:
 943        """Column index where the right half begins, or ``None``."""
 944        return self._right_offset
 945
 946    @staticmethod
 947    def from_split(
 948        split_grids: Split["SegmentedTable"], offsets: Split[Point]
 949    ) -> "SegmentedTable":
 950        """
 951        Convert two ``SegmentedTable`` objects into one that can segment the original (non-cropped) image.
 952
 953        Args:
 954            split_grids (Split[SegmentedTable]): SegmentedTable objects for the left and right part of the table
 955            offsets (Split[tuple[int, int]]): the offsets in the original image where each crop started
 956
 957        Returns:
 958            SegmentedTable: a merged grid spanning both halves.
 959
 960        Raises:
 961            ValueError: if no row is fully populated in both halves.
 962        """
 963
 964        def offset_points(points, offset):
 965            return [
 966                [
 967                    (p[0] + offset[0], p[1] + offset[1]) if p is not None else None
 968                    for p in row
 969                ]
 970                for row in points
 971            ]
 972
 973        split_points = split_grids.apply(
 974            lambda grid, offset: offset_points(grid.points, offset), offsets
 975        )
 976        points = []
 977        rows = min(split_grids.left.rows, split_grids.right.rows)
 978        for row in range(rows + 1):
 979            left_row = split_points.left[row]
 980            right_row = split_points.right[row]
 981
 982            # Skip rows that contain None values
 983            if any(p is None for p in left_row) or any(p is None for p in right_row):
 984                logger.warning(
 985                    f"Skipping row {row} in from_split due to incomplete grid data"
 986                )
 987                continue
 988
 989            row_points = []
 990            row_points.extend(left_row)
 991            row_points.extend(right_row)
 992            points.append(row_points)
 993        if not points:
 994            raise ValueError(
 995                "Cannot create SegmentedTable from split: no complete rows found in both grids"
 996            )
 997        table_grid = SegmentedTable(points, split_grids.left.cols)
 998        return table_grid
 999
1000    def save(self, path: str | Path):
1001        """
1002        Persist the table grid to a JSON file.
1003
1004        Saves the grid corner points and right_offset (for split tables) to disk,
1005        allowing the grid to be reloaded later without re-running detection.
1006
1007        Args:
1008            path: Path to save the JSON file.
1009
1010        Example:
1011            >>> grid = taulu.segment_table("table.png")
1012            >>> grid.save("grid.json")
1013        """
1014        with open(path, "w") as f:
1015            json.dump({"points": self.points, "right_offset": self._right_offset}, f)
1016
1017    @staticmethod
1018    def from_saved(path: str | Path) -> "SegmentedTable":
1019        """
1020        Load a previously saved SegmentedTable from a JSON file.
1021
1022        Args:
1023            path: Path to the JSON file created by `save()`.
1024
1025        Returns:
1026            A SegmentedTable instance with the saved corner points.
1027
1028        Example:
1029            >>> grid = SegmentedTable.from_saved("grid.json")
1030            >>> cell = grid.crop_cell(image, (0, 0))
1031        """
1032        with open(path) as f:
1033            points = json.load(f)
1034            right_offset = points.get("right_offset", None)
1035            points = [[(p[0], p[1]) for p in pointes] for pointes in points["points"]]
1036            return SegmentedTable(points, right_offset)
1037
1038    def add_left_col(self, width: int):
1039        """
1040        Prepend a column to the grid by shifting the first column ``width``
1041        pixels to the left and inserting it as a new column.
1042
1043        Args:
1044            width: Width of the new column in pixels.
1045        """
1046        for row in self._points:
1047            first = row[0]
1048            new_first = (first[0] - width, first[1])
1049            row.insert(0, new_first)
1050
1051    def add_top_row(self, height: int):
1052        """
1053        Prepend a row to the grid by shifting the first row ``height`` pixels
1054        upward and inserting it as a new row.
1055
1056        Args:
1057            height: Height of the new row in pixels.
1058        """
1059        new_row = []
1060        for point in self._points[0]:
1061            new_row.append((point[0], point[1] - height))
1062
1063        self.points.insert(0, new_row)
1064
1065    def _surrounds(self, rect: list[Point], point: tuple[float, float]) -> bool:
1066        """Check if ``point`` (x, y) lies inside the quadrilateral ``rect``
1067        (lt, rt, rb, lb)."""
1068        lt, rt, rb, lb = rect
1069        x, y = point
1070
1071        top = _Rule(*lt, *rt)
1072        if top._y_at_x(x) > y:
1073            return False
1074
1075        right = _Rule(*rt, *rb)
1076        if right._x_at_y(y) < x:
1077            return False
1078
1079        bottom = _Rule(*lb, *rb)
1080        if bottom._y_at_x(x) < y:
1081            return False
1082
1083        left = _Rule(*lb, *lt)
1084        if left._x_at_y(y) > x:
1085            return False
1086
1087        return True
1088
1089    def cell(self, point: tuple[float, float]) -> tuple[int, int]:
1090        """
1091        Get the cell indices (row, col) containing a pixel coordinate.
1092
1093        Searches through all cells to find which one contains the given point,
1094        accounting for the non-rectangular (perspective-warped) cell boundaries.
1095
1096        Args:
1097            point: Pixel coordinates (x, y) in the original image.
1098
1099        Returns:
1100            (row, col) indices of the containing cell, or (-1, -1) if the point
1101            is outside all cells.
1102
1103        Example:
1104            >>> grid = taulu.segment_table("table.png")
1105            >>> row, col = grid.cell((150, 200))
1106            >>> if row >= 0:
1107            ...     print(f"Point is in cell ({row}, {col})")
1108        """
1109        for r in range(len(self._points) - 1):
1110            offset = 0
1111            for c in range(len(self.row(0)) - 1):
1112                if self._right_offset is not None and c == self._right_offset:
1113                    offset = -1
1114                    continue
1115
1116                if self._surrounds(
1117                    [
1118                        self._points[r][c],
1119                        self._points[r][c + 1],
1120                        self._points[r + 1][c + 1],
1121                        self._points[r + 1][c],
1122                    ],
1123                    point,
1124                ):
1125                    return (r, c + offset)
1126
1127        return (-1, -1)
1128
1129    def cell_polygon(self, cell: tuple[int, int]) -> tuple[Point, Point, Point, Point]:
1130        """
1131        Get the four corner coordinates of a cell.
1132
1133        Returns the corners in clockwise order starting from top-left,
1134        suitable for use with OpenCV drawing functions.
1135
1136        Args:
1137            cell: Cell indices as (row, col).
1138
1139        Returns:
1140            Four corner points as ((x,y), (x,y), (x,y), (x,y)) in order:
1141            top-left, top-right, bottom-right, bottom-left.
1142
1143        Raises:
1144            TauluException: If row or col indices are out of bounds.
1145
1146        Example:
1147            >>> lt, rt, rb, lb = grid.cell_polygon((0, 0))
1148            >>> pts = np.array([lt, rt, rb, lb], dtype=np.int32)
1149            >>> cv2.polylines(image, [pts], True, (0, 255, 0), 2)
1150        """
1151        r, c = cell
1152
1153        self._check_row_idx(r)
1154        self._check_col_idx(c)
1155
1156        if self._right_offset is not None and c >= self._right_offset:
1157            c = c + 1
1158
1159        return (
1160            self._points[r][c],
1161            self._points[r][c + 1],
1162            self._points[r + 1][c + 1],
1163            self._points[r + 1][c],
1164        )
1165
1166    def region(
1167        self, start: tuple[int, int], end: tuple[int, int]
1168    ) -> tuple[Point, Point, Point, Point]:
1169        """
1170        Get the bounding polygon for a rectangular region of cells.
1171
1172        Returns the four corner coordinates that enclose all cells from
1173        start to end (inclusive).
1174
1175        Args:
1176            start: Top-left cell as (row, col).
1177            end: Bottom-right cell as (row, col).
1178
1179        Returns:
1180            Four corner points (lt, rt, rb, lb) enclosing the region,
1181            each as (x, y) pixel coordinates.
1182
1183        Raises:
1184            TauluException: If any row or col indices are out of bounds.
1185
1186        Example:
1187            >>> # Get bounding box for cells (0,0) through (2,3)
1188            >>> lt, rt, rb, lb = grid.region((0, 0), (2, 3))
1189        """
1190        r0, c0 = start
1191        r1, c1 = end
1192
1193        self._check_row_idx(r0)
1194        self._check_row_idx(r1)
1195        self._check_col_idx(c0)
1196        self._check_col_idx(c1)
1197
1198        if self._right_offset is not None and c0 >= self._right_offset:
1199            c0 = c0 + 1
1200
1201        if self._right_offset is not None and c1 >= self._right_offset:
1202            c1 = c1 + 1
1203
1204        lt = self._points[r0][c0]
1205        rt = self._points[r0][c1 + 1]
1206        rb = self._points[r1 + 1][c1 + 1]
1207        lb = self._points[r1 + 1][c0]
1208
1209        return lt, rt, rb, lb
1210
1211    def visualize_points(self, img: MatLike):
1212        """
1213        Draw the detected table points on the image for visual verification
1214        """
1215        import colorsys
1216
1217        def clr(index, total_steps):
1218            hue = index / total_steps  # Normalized hue between 0 and 1
1219            r, g, b = colorsys.hsv_to_rgb(hue, 1.0, 1.0)
1220            return int(r * 255), int(g * 255), int(b * 255)
1221
1222        for i, row in enumerate(self._points):
1223            for p in row:
1224                cv.circle(img, p, 4, clr(i, len(self._points)), -1)
1225
1226        imu.show(img)
1227
1228    def text_regions(
1229        self, img: MatLike, row: int, margin_x: int = 10, margin_y: int = -3
1230    ) -> list[tuple[tuple[int, int], tuple[int, int]]]:
1231        """
1232        Split a row into spans of consecutive cells whose vertical separators
1233        are obscured by text (i.e. continuous handwriting crosses the rule).
1234
1235        Args:
1236            img: Source table image.
1237            row: Row index to scan.
1238            margin_x: Horizontal margin around each rule crop, in pixels.
1239            margin_y: Vertical margin around each rule crop, in pixels.
1240
1241        Returns:
1242            List of ``((row, start_col), (row, end_col))`` spans (inclusive).
1243        """
1244
1245        def vertical_rule_crop(row: int, col: int):
1246            self._check_col_idx(col)
1247            self._check_row_idx(row)
1248
1249            if self._right_offset is not None and col >= self._right_offset:
1250                col = col + 1
1251
1252            top = self._points[row][col]
1253            bottom = self._points[row + 1][col]
1254
1255            left = int(min(top[0], bottom[0]))
1256            right = int(max(top[0], bottom[0]))
1257
1258            return img[
1259                int(top[1]) - margin_y : int(bottom[1]) + margin_y,
1260                left - margin_x : right + margin_x,
1261            ]
1262
1263        result = []
1264
1265        start = None
1266        for col in range(self.cols):
1267            crop = vertical_rule_crop(row, col)
1268            text_over_score = imu.text_presence_score(crop)
1269            text_over = text_over_score > -0.10
1270
1271            if not text_over:
1272                if start is not None:
1273                    result.append(((row, start), (row, col - 1)))
1274                start = col
1275
1276        if start is not None:
1277            result.append(((row, start), (row, self.cols - 1)))
1278
1279        return result

 19class Split[T]:
 20    """
 21    Container for paired left/right data with convenient manipulation methods.
 22
 23    The Split class is designed for working with table images that span two pages
 24    or have distinct left and right sections. It allows you to:
 25    - Store related data for both sides
 26    - Apply functions to both sides simultaneously
 27    - Access attributes/methods of contained objects transparently
 28
 29    Examples:
 30        >>> # Create a split with different parameters for each side
 31        >>> thresholds = Split(0.25, 0.30)
 32        >>>
 33        >>> # Apply a function to both sides
 34        >>> images = Split(left_img, right_img)
 35        >>> processed = images.apply(lambda img: cv2.blur(img, (5, 5)))
 36        >>>
 37        >>> # Use with different parameters per side
 38        >>> results = images.apply(
 39        ...     lambda img, k: sauvola_threshold(img, k),
 40        ...     k=thresholds  # k.left used for left img, k.right for right
 41        ... )
 42        >>>
 43        >>> # Access methods of contained objects directly
 44        >>> templates = Split(template_left, template_right)
 45        >>> widths = templates.cell_widths(0)  # Calls on both templates
 46
 47    Type Parameters:
 48        T: The type of objects stored in left and right
 49    """
 50
 51    @classmethod
 52    def __get_pydantic_core_schema__(
 53        cls,
 54        source_type: Any,
 55        handler: GetCoreSchemaHandler,
 56    ) -> core_schema.CoreSchema:
 57        args = get_args(source_type)
 58        inner_type = args[0] if args else Any
 59
 60        inner_schema = handler.generate_schema(inner_type)
 61
 62        def validate_split(value: Any) -> Split:
 63            if isinstance(value, Split):
 64                return value
 65            if isinstance(value, dict) and "left" in value and "right" in value:
 66                return Split(value["left"], value["right"])
 67            raise ValueError(
 68                f"Expected Split instance or dict with 'left'/'right' keys, got {type(value)}"
 69            )
 70
 71        return core_schema.no_info_plain_validator_function(
 72            validate_split,
 73            serialization=core_schema.plain_serializer_function_ser_schema(
 74                lambda v: {"left": v.left, "right": v.right},
 75                info_arg=False,
 76            ),
 77            metadata={
 78                "pydantic_js_functions": [
 79                    lambda _schema, handler: {
 80                        "type": "object",
 81                        "properties": {
 82                            "left": handler(inner_schema),
 83                            "right": handler(inner_schema),
 84                        },
 85                        "required": ["left", "right"],
 86                        "additionalProperties": False,
 87                    }
 88                ]
 89            },
 90        )
 91
 92    def __init__(self, left: T | None = None, right: T | None = None):
 93        """
 94        Initialize a Split container.
 95
 96        Args:
 97            left: Data for the left side
 98            right: Data for the right side
 99
100        Note:
101            Both can initially be None. Use the `append` method or set
102            properties directly to populate.
103        """
104        self._left = left
105        self._right = right
106
107    @property
108    def left(self) -> T:
109        """The left value. Asserts it has been set."""
110        assert self._left is not None
111        return self._left
112
113    @left.setter
114    def left(self, value: T):
115        self._left = value
116
117    @property
118    def right(self) -> T:
119        """The right value. Asserts it has been set."""
120        assert self._right is not None
121        return self._right
122
123    @right.setter
124    def right(self, value: T):
125        self._right = value
126
127    def append(self, value: T):
128        """Set ``left`` if unset, otherwise set ``right``."""
129        if self._left is None:
130            self._left = value
131        else:
132            self._right = value
133
134    def __repr__(self) -> str:
135        return f"left: {self._left}, right: {self._right}"
136
137    def __iter__(self):
138        assert self._left is not None
139        assert self._right is not None
140        return iter((self._left, self._right))
141
142    def __getitem__(self, index: bool | int) -> T:
143        assert self._left is not None
144        assert self._right is not None
145        if int(index) == 0:
146            return self._left
147        else:
148            return self._right
149
150    def apply(
151        self,
152        funcs: Split[Callable[..., V]] | Callable[..., V],
153        *args,
154        **kwargs,
155    ) -> Split[V]:
156        """
157        Call ``funcs`` on each side and return a new Split of the results.
158
159        ``self.left`` (resp. ``self.right``) is passed as the first positional
160        argument. Any extra ``args``/``kwargs`` that are themselves a `Split`
161        are unpacked per side; non-Split values are forwarded unchanged.
162
163        Args:
164            funcs: A single callable applied to both sides, or a `Split` of
165                callables for per-side functions.
166
167        Returns:
168            Split[V]: results of the per-side calls.
169        """
170        if not isinstance(funcs, Split):
171            funcs = Split(funcs, funcs)
172
173        def get_arg(side: str, arg):
174            if isinstance(arg, Split):
175                return getattr(arg, side)
176            return arg
177
178        def call(side: str):
179            func = getattr(funcs, side)
180            target = getattr(self, side)
181
182            side_args = [get_arg(side, arg) for arg in args]
183            side_kwargs = {k: get_arg(side, v) for k, v in kwargs.items()}
184
185            return func(target, *side_args, **side_kwargs)
186
187        return Split(call("left"), call("right"))
188
189    def __getattr__(self, attr_name: str):
190        if attr_name in self.__dict__:
191            return getattr(self, attr_name)
192
193        def wrapper(*args, **kwargs):
194            return self.apply(
195                Split(
196                    getattr(self.left.__class__, attr_name),
197                    getattr(self.right.__class__, attr_name),
198                ),
199                *args,
200                **kwargs,
201            )
202
203        return wrapper