Release AIFlow Math Ink 0.5 geometric gridding layer

Standalone Apache-2.0 stroke geometry layer with method documentation, architecture SVG, tests, and no OCR model artifacts.

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+build/
+dist/
+*.egg-info/
+outputs/
+

LICENSE

@@ -0,0 +1,193 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      Copyright 2026 AIFlow contributors
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+

NOTICE

@@ -0,0 +1,9 @@
+AIFlow Math Ink 0.5
+Copyright 2026 AIFlow contributors
+
+This distribution contains only the AIFlow geometric gridding implementation.
+It contains no OCR model, weights, tokenizer, dataset, or third-party source.
+
+Pillow is an optional install-time runtime dependency and is not redistributed.
+External OCR recognizers are separate works and are governed by their own terms.
+

README.md

@@ -0,0 +1,119 @@
+---
+license: apache-2.0
+language:
+  - en
+  - ko
+tags:
+  - handwriting
+  - mathematical-expression-recognition
+  - preprocessing
+  - stroke-grouping
+  - geometry
+library_name: aiflow-math-ink
+pipeline_tag: image-to-text
+---
+
+# AIFlow Math Ink 0.5
+
+AIFlow Math Ink 0.5 is a **model-agnostic geometric gridding layer** for online
+handwritten mathematics. It converts ordered pen strokes into spatially coherent
+formula cells and renders one clean image per cell.
+
+> This repository contains no OCR model, model weight, tokenizer, training data,
+> or generated prediction. It is a deterministic preprocessing layer only.
+
+The output images can be passed to any image-to-LaTeX recognizer. They are
+interface-compatible with TexTeller-style image batches, but TexTeller is not
+included, redistributed, modified, or required by this repository.
+
+![AIFlow Math Ink 0.5 pipeline](assets/architecture.svg)
+
+## Why this layer exists
+
+An image-to-LaTeX model normally expects one coherent expression image. A pen
+canvas may instead contain multiple rows, detached superscripts, fractions, or
+matrix delimiters. AIFlow Math Ink 0.5 uses the original stroke geometry to
+partition that canvas before recognition.
+
+The layer:
+
+1. validates bounded UTF-8 JSON-like stroke events;
+2. computes width-aware stroke bounding boxes;
+3. estimates a scale from the median stroke height;
+4. creates same-baseline and local-attachment edges;
+5. adds structural bridge edges for fraction bars and tall delimiters;
+6. extracts connected components with a disjoint-set structure;
+7. sorts cells in stable two-dimensional reading order; and
+8. re-renders only the member strokes of each cell.
+
+This is a transparent heuristic algorithm, not a trained neural-network layer.
+
+## Installation
+
+```bash
+pip install Pillow
+```
+
+Clone this repository and add `src` to your Python path, or install it locally:
+
+```bash
+pip install -e .
+```
+
+## Minimal example
+
+```python
+from PIL import Image
+
+from aiflow_math_ink_05 import GridConfig, Stroke, build_formula_grids, render_grid_images
+
+strokes = [
+    Stroke(0, ((24, 20), (36, 20)), 3.0),
+    Stroke(1, ((10, 42), (60, 42)), 3.0),
+    Stroke(2, ((24, 64), (36, 64)), 3.0),
+]
+
+grids = build_formula_grids(strokes, GridConfig())
+images = render_grid_images(Image.new("RGB", (80, 90), "white"), strokes, grids)
+
+for grid, image in zip(grids, images, strict=True):
+    print(grid.stroke_ids)
+    image.save(f"cell-{grid.index}.png")
+```
+
+For an existing API payload, use `parse_writing_events()` before
+`build_formula_grids()`. See [`examples/basic.py`](examples/basic.py).
+
+## Recognizer compatibility
+
+`render_grid_images()` returns ordinary RGB `PIL.Image.Image` objects. A
+recognizer can consume the list as a batch without importing this package into
+its model implementation. TexTeller compatibility means only this image-level
+interface; no TexTeller component is included.
+
+## Method and complexity
+
+The complete method, equations, assumptions, and limitations are documented in
+[`docs/METHOD.md`](docs/METHOD.md).
+
+For \(n\) accepted strokes, pair construction is \(O(n^2)\), disjoint-set
+operations are effectively near-linear, and rendering is proportional to the
+number of retained points plus output pixels. Input caps are mandatory in
+server environments; the parser defaults to 2,000 strokes and 200,000 total
+points.
+
+## Scope and limitations
+
+- This release performs geometry-based grouping, not symbol recognition.
+- It does not infer LaTeX, semantics, or correctness.
+- Thresholds are scale-adaptive but remain heuristic.
+- Dense overlapping notes and unusual layouts can over-merge.
+- The method has not been presented here as a peer-reviewed contribution.
+- The repository ships no dataset and makes no benchmark claim.
+
+## License
+
+The original code in this repository is licensed under Apache License 2.0.
+Pillow is an install-time dependency and is not vendored. External recognizers
+are separate works governed by their own licenses.
+

docs/LICENSE_REVIEW.md

@@ -0,0 +1,60 @@
+# License review
+
+Review date: 2026-07-25
+
+## Distribution boundary
+
+This repository distributes:
+
+- original AIFlow geometric grouping source;
+- original documentation and SVG artwork;
+- tests and a small synthetic example.
+
+It does not distribute:
+
+- an OCR model or model architecture implementation;
+- model weights, tokenizer files, or inference configuration;
+- a dataset or user handwriting;
+- source copied from an external recognizer;
+- Pillow source or binaries.
+
+## Project license
+
+The distributed work is offered under Apache License 2.0. The repository
+includes the full `LICENSE` text and a `NOTICE` file. Apache-2.0 permits
+commercial use, modification, and redistribution subject to its notice,
+license-copy, and modification-marking conditions. It also includes an express
+patent grant and warranty disclaimer.
+
+Primary source:
+https://www.apache.org/licenses/LICENSE-2.0
+
+## Runtime dependency
+
+Pillow is declared as an install-time dependency and is not vendored. Pillow is
+licensed under the open-source MIT-CMU license. Its license permits use, copy,
+modification, and distribution subject to preservation of its copyright and
+permission notice.
+
+Primary source:
+https://github.com/python-pillow/Pillow/blob/main/LICENSE
+
+## Optional recognizer interoperability
+
+The package returns ordinary RGB Pillow images. Compatibility with an external
+recognizer is an interface statement only and does not create a bundled or
+derived distribution of that recognizer. Users must obtain and operate any
+external recognizer separately under its own license.
+
+TexTeller's official repository currently declares Apache-2.0, but no TexTeller
+artifact is included here.
+
+Primary source:
+https://github.com/OleehyO/TexTeller
+
+## Conclusion
+
+The repository is suitable for publication as a standalone Apache-2.0 source
+release, assuming the uploader is authorized to license the AIFlow source. This
+is a technical license review, not jurisdiction-specific legal advice.
+

docs/METHOD.md

@@ -0,0 +1,152 @@
+# AIFlow Math Ink 0.5: geometric gridding method
+
+## Abstract
+
+AIFlow Math Ink 0.5 is a deterministic preprocessing method for partitioning
+online handwritten mathematics into image cells suitable for downstream
+image-to-LaTeX recognition. It uses stroke trajectories and pen widths rather
+than predicted symbols. The method constructs a sparse semantic approximation
+through pairwise geometric predicates, augments it with fraction-bar and tall
+delimiter bridges, and extracts connected components with disjoint-set union.
+It is not a learned model and makes no claim of semantic parsing.
+
+## 1. Input representation
+
+Let a canvas contain ordered strokes
+
+\[
+\mathcal{S} = \{s_i\}_{i=1}^{n},
+\qquad
+s_i = (\mathrm{id}_i, \{(x_{ik},y_{ik})\}_{k=1}^{m_i}, w_i).
+\]
+
+Each stroke has a stable identifier, an ordered point sequence, and pen width
+\(w_i\). Its axis-aligned bounding box expands the point extrema by
+\(w_i/2\). This preserves the visible support of thick strokes.
+
+The parser applies finite caps to stroke count, points per stroke, total points,
+coordinate magnitude, and pen width. These caps are part of the runtime safety
+contract rather than the mathematical grouping rule.
+
+## 2. Scale estimation
+
+Let \(h_i\) be the height of stroke box \(B_i\). The characteristic scale is
+
+\[
+\tilde h = \operatorname{median}_{i}(h_i).
+\]
+
+Median height is resistant to a small number of long fraction bars or tall
+delimiters. Four distances are then defined:
+
+\[
+\tau_b = \max(24, 0.50\tilde h), \quad
+\tau_x = \max(72, 1.25\tilde h),
+\]
+
+\[
+\tau_s = \max(52, 0.80\tilde h), \quad
+\tau_a = \max(18, 0.18\tilde h).
+\]
+
+The constants are defaults exposed by `GridConfig`; they are not learned
+parameters.
+
+## 3. Geometric relation graph
+
+For boxes \(B_i,B_j\), let \(g_x(i,j)\) and \(g_y(i,j)\) be non-negative
+axis gaps, and let \(c_y(i)\) be vertical center.
+
+A same-baseline edge is created when
+
+\[
+|c_y(i)-c_y(j)| \le \tau_b
+\quad\land\quad
+g_x(i,j) \le \tau_x.
+\]
+
+A local-attachment edge handles detached pieces and scripts:
+
+\[
+g_x(i,j)\le\tau_a
+\quad\land\quad
+g_y(i,j)\le\tau_a
+\]
+
+\[
+\quad\land\quad
+|c_y(i)-c_y(j)|
+\le 1.35\max(h_i,h_j)+\tau_a.
+\]
+
+These predicates intentionally favor recall of one coherent expression. They
+can over-merge dense neighboring work, which is a documented limitation.
+
+## 4. Structural bridges
+
+A box is treated as a horizontal bridge candidate when
+
+\[
+\operatorname{width}(B_i)\ge30
+\quad\land\quad
+\operatorname{width}(B_i)\ge4\operatorname{height}(B_i).
+\]
+
+It connects to a nearby box when horizontal overlap is at least 20% of the
+smaller width and vertical axis gap is at most \(\tau_s\). This approximates the
+role of a fraction bar without recognizing its symbol.
+
+A box is treated as a vertical bridge candidate when
+
+\[
+\operatorname{height}(B_i)\ge45
+\quad\land\quad
+\operatorname{height}(B_i)\ge2.5\operatorname{width}(B_i).
+\]
+
+It connects nearby vertically aligned strokes, approximating tall parentheses,
+brackets, absolute-value marks, and matrix delimiters.
+
+## 5. Connected components
+
+All accepted relations are union operations over a disjoint-set forest with
+path compression and union by size. Each connected component becomes one
+formula cell. The cell boundary is the union of member boxes plus configurable
+padding.
+
+Cells are deterministically ordered by a quantized vertical band followed by
+their left coordinate. This is a stable geometric order, not a full
+two-dimensional mathematical parse.
+
+## 6. Rendering contract
+
+For every cell, member strokes are redrawn on a white RGB canvas and cropped to
+the padded component boundary. Redrawing suppresses unrelated marks that happen
+to occupy the rectangular crop. The returned object is a list of ordinary
+`PIL.Image.Image` values and contains no recognizer-specific tensor transform.
+
+This image-level contract is compatible with downstream recognizers that accept
+formula image batches, including TexTeller-style pipelines. No recognizer is
+included.
+
+## 7. Complexity
+
+The pairwise relation phase is \(O(n^2)\). Disjoint-set operations take
+\(O(\alpha(n))\) amortized time, where \(\alpha\) is the inverse Ackermann
+function. Rendering cost is proportional to retained stroke points and output
+pixels. Bounded input size is therefore required for untrusted server traffic.
+
+## 8. Scientific status and limitations
+
+AIFlow Math Ink 0.5 is an engineering heuristic with explicit assumptions:
+
+- axis-aligned boxes are sufficient local geometry;
+- median stroke height approximates device scale;
+- long horizontal and vertical strokes are useful structural bridges;
+- connected components are adequate formula-cell hypotheses.
+
+The release does not include a learned grouping head, probabilistic confidence,
+ground-truth dataset, or benchmark claim. Appropriate evaluation would report
+partition exact match, over-merge and under-merge rates, writer/device-disjoint
+slices, and end-to-end expression accuracy separately.
+

examples/basic.py

@@ -0,0 +1,44 @@
+"""AIFlow Math Ink 0.5의 JSON-like stroke 입력 예시."""
+
+from pathlib import Path
+
+from PIL import Image
+
+from aiflow_math_ink_05 import (
+    build_formula_grids,
+    parse_writing_events,
+    render_grid_images,
+)
+
+
+def main() -> None:
+    """필요 변수: 예제 stroke payload. 작동 원리: 수식 셀을 만들고 UTF-8 경로 아래 PNG로 저장한다."""
+    events = [
+        {
+            "stroke_id": 0,
+            "width": 3,
+            "points": [{"x": 24, "y": 20}, {"x": 36, "y": 20}],
+        },
+        {
+            "stroke_id": 1,
+            "width": 3,
+            "points": [{"x": 10, "y": 42}, {"x": 60, "y": 42}],
+        },
+        {
+            "stroke_id": 2,
+            "width": 3,
+            "points": [{"x": 24, "y": 64}, {"x": 36, "y": 64}],
+        },
+    ]
+    strokes = parse_writing_events(events)
+    grids = build_formula_grids(strokes)
+    images = render_grid_images(Image.new("RGB", (80, 90), "white"), strokes, grids)
+    output_directory = Path("outputs")
+    output_directory.mkdir(exist_ok=True)
+    for grid, image in zip(grids, images, strict=True):
+        image.save(output_directory / f"cell-{grid.index}.png")
+
+
+if __name__ == "__main__":
+    main()
+

pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aiflow-math-ink"
+version = "0.5.0"
+description = "Model-agnostic geometric gridding for online handwritten mathematics"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.11"
+dependencies = ["Pillow>=10,<12"]
+
+[project.optional-dependencies]
+test = ["pytest>=8,<9"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

src/aiflow_math_ink_05/__init__.py

@@ -0,0 +1,22 @@
+"""AIFlow Math Ink 0.5 공개 인터페이스."""
+
+from .grid import (
+    FormulaGrid,
+    GridConfig,
+    Stroke,
+    StrokeBox,
+    build_formula_grids,
+    parse_writing_events,
+    render_grid_images,
+)
+
+__all__ = [
+    "FormulaGrid",
+    "GridConfig",
+    "Stroke",
+    "StrokeBox",
+    "build_formula_grids",
+    "parse_writing_events",
+    "render_grid_images",
+]
+

src/aiflow_math_ink_05/grid.py

@@ -0,0 +1,314 @@
+"""온라인 필기 stroke를 모델 독립적인 2차원 수식 셀로 묶는다."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from statistics import median
+from typing import Any, Sequence
+
+from PIL import Image, ImageDraw
+
+
+@dataclass(frozen=True, slots=True)
+class GridConfig:
+    """필요 변수: 기하 임계값과 입력 상한이다.
+    작동 원리: 고정 최소값과 대표 획 높이 비율을 함께 사용해 기기 좌표계 변화에 대응한다.
+    """
+
+    baseline_tolerance: float = 24.0
+    expression_gap: float = 72.0
+    structure_gap: float = 52.0
+    padding: float = 12.0
+    max_strokes: int = 2_000
+    max_points_per_stroke: int = 4_096
+    max_total_points: int = 200_000
+    coordinate_limit: float = 20_000.0
+
+
+@dataclass(frozen=True, slots=True)
+class StrokeBox:
+    """필요 변수: 좌·상·우·하 경계다.
+    작동 원리: 획과 수식 셀의 축 정렬 경계 및 병합 연산을 제공한다.
+    """
+
+    left: float
+    top: float
+    right: float
+    bottom: float
+
+    @property
+    def width(self) -> float:
+        """필요 변수: 좌우 좌표. 작동 원리: 음수가 아닌 폭을 반환한다."""
+        return max(0.0, self.right - self.left)
+
+    @property
+    def height(self) -> float:
+        """필요 변수: 상하 좌표. 작동 원리: 음수가 아닌 높이를 반환한다."""
+        return max(0.0, self.bottom - self.top)
+
+    @property
+    def center_y(self) -> float:
+        """필요 변수: 상하 좌표. 작동 원리: 같은 기준선 판정용 중심을 반환한다."""
+        return (self.top + self.bottom) / 2.0
+
+    def union(self, other: "StrokeBox") -> "StrokeBox":
+        """필요 변수: 다른 경계. 작동 원리: 두 경계를 포함하는 최소 경계를 만든다."""
+        return StrokeBox(
+            min(self.left, other.left),
+            min(self.top, other.top),
+            max(self.right, other.right),
+            max(self.bottom, other.bottom),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Stroke:
+    """필요 변수: 안정적인 획 ID·순서 있는 점·선 굵기다.
+    작동 원리: 선 반지름을 포함한 경계를 계산해 필기 폭을 보존한다.
+    """
+
+    stroke_id: int
+    points: tuple[tuple[float, float], ...]
+    width: float = 3.0
+
+    @property
+    def box(self) -> StrokeBox:
+        """필요 변수: 필기점·굵기. 작동 원리: 선 반지름까지 포함한 경계를 계산한다."""
+        radius = self.width / 2.0
+        return StrokeBox(
+            min(point[0] for point in self.points) - radius,
+            min(point[1] for point in self.points) - radius,
+            max(point[0] for point in self.points) + radius,
+            max(point[1] for point in self.points) + radius,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class FormulaGrid:
+    """필요 변수: 셀 순번·경계·소속 획 ID다.
+    작동 원리: 인식기와 무관한 결정적 수식 셀 계약을 표현한다.
+    """
+
+    index: int
+    box: StrokeBox
+    stroke_ids: tuple[int, ...]
+
+
+class _DisjointSet:
+    """필요 변수: 획 개수. 작동 원리: 경로 압축과 크기 기준 병합으로 연결 성분을 관리한다."""
+
+    def __init__(self, size: int) -> None:
+        """필요 변수: 원소 수. 작동 원리: 각 획을 독립 집합으로 초기화한다."""
+        self.parent = list(range(size))
+        self.size = [1] * size
+
+    def find(self, value: int) -> int:
+        """필요 변수: 획 인덱스. 작동 원리: 대표를 찾는 동안 경로를 압축한다."""
+        while self.parent[value] != value:
+            self.parent[value] = self.parent[self.parent[value]]
+            value = self.parent[value]
+        return value
+
+    def union(self, first: int, second: int) -> None:
+        """필요 변수: 두 획 인덱스. 작동 원리: 작은 트리를 큰 트리 아래에 결합한다."""
+        root_first = self.find(first)
+        root_second = self.find(second)
+        if root_first == root_second:
+            return
+        if self.size[root_first] < self.size[root_second]:
+            root_first, root_second = root_second, root_first
+        self.parent[root_second] = root_first
+        self.size[root_first] += self.size[root_second]
+
+
+def parse_writing_events(value: Any, config: GridConfig | None = None) -> list[Stroke]:
+    """필요 변수: JSON 유사 writing events와 선택 설정이다.
+    작동 원리: 유한한 좌표·점·획만 상한 안에서 받아 안전한 불변 Stroke로 정규화한다.
+    """
+    settings = config or GridConfig()
+    if not isinstance(value, list):
+        return []
+    total_points = 0
+    strokes: list[Stroke] = []
+    for fallback_id, item in enumerate(value[: settings.max_strokes]):
+        if not isinstance(item, dict) or not isinstance(item.get("points"), list):
+            continue
+        points: list[tuple[float, float]] = []
+        for point in item["points"][: settings.max_points_per_stroke]:
+            if not isinstance(point, dict):
+                continue
+            try:
+                x = float(point["x"])
+                y = float(point["y"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            if abs(x) <= settings.coordinate_limit and abs(y) <= settings.coordinate_limit:
+                points.append((x, y))
+        if len(points) < 2:
+            continue
+        if total_points + len(points) > settings.max_total_points:
+            break
+        try:
+            stroke_id = int(item.get("stroke_id", fallback_id))
+            width = min(32.0, max(0.5, float(item.get("width", 3.0))))
+        except (TypeError, ValueError):
+            continue
+        strokes.append(Stroke(stroke_id, tuple(points), width))
+        total_points += len(points)
+    return strokes
+
+
+def build_formula_grids(
+    strokes: Sequence[Stroke],
+    config: GridConfig | None = None,
+) -> list[FormulaGrid]:
+    """필요 변수: 정규화된 획과 선택 설정이다.
+    작동 원리: 기준선·근접 부착·구조선 관계 그래프의 연결 성분을 2차원 수식 셀로 만든다.
+    """
+    if not strokes:
+        return []
+    settings = config or GridConfig()
+    boxes = [stroke.box for stroke in strokes]
+    typical_height = median(box.height for box in boxes)
+    baseline = max(settings.baseline_tolerance, typical_height * 0.50)
+    expression_gap = max(settings.expression_gap, typical_height * 1.25)
+    structure_gap = max(settings.structure_gap, typical_height * 0.80)
+    attachment_gap = max(18.0, typical_height * 0.18)
+    groups = _DisjointSet(len(strokes))
+
+    for first in range(len(strokes)):
+        for second in range(first + 1, len(strokes)):
+            horizontal_gap = _axis_gap(
+                boxes[first].left,
+                boxes[first].right,
+                boxes[second].left,
+                boxes[second].right,
+            )
+            vertical_gap = _axis_gap(
+                boxes[first].top,
+                boxes[first].bottom,
+                boxes[second].top,
+                boxes[second].bottom,
+            )
+            center_gap = abs(boxes[first].center_y - boxes[second].center_y)
+            same_line = center_gap <= baseline and horizontal_gap <= expression_gap
+            attachment = (
+                horizontal_gap <= attachment_gap
+                and vertical_gap <= attachment_gap
+                and center_gap
+                <= max(boxes[first].height, boxes[second].height) * 1.35 + attachment_gap
+            )
+            if same_line or attachment:
+                groups.union(first, second)
+
+    _join_structural_bridges(boxes, groups, structure_gap)
+    members: dict[int, list[int]] = {}
+    for index in range(len(strokes)):
+        members.setdefault(groups.find(index), []).append(index)
+
+    raw: list[tuple[StrokeBox, tuple[int, ...]]] = []
+    for indices in members.values():
+        box = boxes[indices[0]]
+        for index in indices[1:]:
+            box = box.union(boxes[index])
+        padded = StrokeBox(
+            box.left - settings.padding,
+            box.top - settings.padding,
+            box.right + settings.padding,
+            box.bottom + settings.padding,
+        )
+        raw.append((padded, tuple(sorted(strokes[index].stroke_id for index in indices))))
+
+    raw.sort(key=lambda item: (round(item[0].top / max(1.0, baseline)), item[0].left))
+    return [
+        FormulaGrid(index=index, box=box, stroke_ids=stroke_ids)
+        for index, (box, stroke_ids) in enumerate(raw)
+    ]
+
+
+def render_grid_images(
+    image: Image.Image,
+    strokes: Sequence[Stroke],
+    grids: Sequence[FormulaGrid],
+) -> list[Image.Image]:
+    """필요 변수: 기준 캔버스·원본 획·수식 셀이다.
+    작동 원리: 각 셀의 소속 획만 흰 배경에 재렌더링하고 셀 경계로 잘라 RGB 이미지로 반환한다.
+    """
+    stroke_by_id = {stroke.stroke_id: stroke for stroke in strokes}
+    results: list[Image.Image] = []
+    for grid in grids:
+        canvas = Image.new("RGB", image.size, "white")
+        draw = ImageDraw.Draw(canvas)
+        for stroke_id in grid.stroke_ids:
+            stroke = stroke_by_id.get(stroke_id)
+            if stroke is not None:
+                draw.line(
+                    stroke.points,
+                    fill="black",
+                    width=max(1, round(stroke.width)),
+                    joint="curve",
+                )
+        results.append(_crop(canvas, grid.box))
+    return results
+
+
+def _join_structural_bridges(
+    boxes: Sequence[StrokeBox],
+    groups: _DisjointSet,
+    structure_gap: float,
+) -> None:
+    """필요 변수: 획 경계·집합 구조·구조 거리다.
+    작동 원리: 긴 가로선은 분수선, 긴 세로선은 괄호·행렬 경계 후보로 보고 인접 획을 연결한다.
+    """
+    for bridge_index, bridge in enumerate(boxes):
+        horizontal_bridge = bridge.width >= 30 and bridge.width >= bridge.height * 4
+        vertical_bridge = bridge.height >= 45 and bridge.height >= bridge.width * 2.5
+        if not horizontal_bridge and not vertical_bridge:
+            continue
+        for other_index, other in enumerate(boxes):
+            if other_index == bridge_index:
+                continue
+            if horizontal_bridge:
+                overlap = _overlap(bridge.left, bridge.right, other.left, other.right)
+                denominator = max(1.0, min(bridge.width, other.width))
+                if (
+                    overlap / denominator >= 0.20
+                    and _axis_gap(bridge.top, bridge.bottom, other.top, other.bottom)
+                    <= structure_gap
+                ):
+                    groups.union(bridge_index, other_index)
+            elif (
+                bridge.top - 18 <= other.center_y <= bridge.bottom + 18
+                and _axis_gap(bridge.left, bridge.right, other.left, other.right)
+                <= structure_gap
+            ):
+                groups.union(bridge_index, other_index)
+
+
+def _crop(image: Image.Image, box: StrokeBox) -> Image.Image:
+    """필요 변수: 이미지와 셀 경계. 작동 원리: 경계를 이미지 안 정수 좌표로 제한해 안전하게 자른다."""
+    left = max(0, min(image.width - 1, int(box.left)))
+    top = max(0, min(image.height - 1, int(box.top)))
+    right = max(left + 1, min(image.width, int(box.right + 0.999)))
+    bottom = max(top + 1, min(image.height, int(box.bottom + 0.999)))
+    return image.crop((left, top, right, bottom))
+
+
+def _axis_gap(
+    first_start: float,
+    first_end: float,
+    second_start: float,
+    second_end: float,
+) -> float:
+    """필요 변수: 한 축의 두 구간. 작동 원리: 겹치면 0, 아니면 최근접 끝점 거리를 반환한다."""
+    return max(0.0, max(first_start, second_start) - min(first_end, second_end))
+
+
+def _overlap(
+    first_start: float,
+    first_end: float,
+    second_start: float,
+    second_end: float,
+) -> float:
+    """필요 변수: 한 축의 두 구간. 작동 원리: 두 구간의 교집합 길이를 반환한다."""
+    return max(0.0, min(first_end, second_end) - max(first_start, second_start))

tests/test_grid.py

@@ -0,0 +1,64 @@
+"""AIFlow Math Ink 0.5의 모델 독립적 그리딩 계약을 검증한다."""
+
+from PIL import Image
+
+from aiflow_math_ink_05 import (
+    GridConfig,
+    Stroke,
+    build_formula_grids,
+    parse_writing_events,
+    render_grid_images,
+)
+
+
+def test_fraction_bar_joins_numerator_and_denominator() -> None:
+    """필요 변수: 분자·분수선·분모 획. 작동 원리: 구조선이 세 획을 한 셀로 묶는지 검증한다."""
+    strokes = [
+        Stroke(0, ((24, 20), (36, 20))),
+        Stroke(1, ((10, 42), (60, 42))),
+        Stroke(2, ((24, 64), (36, 64))),
+    ]
+
+    grids = build_formula_grids(strokes)
+
+    assert len(grids) == 1
+    assert grids[0].stroke_ids == (0, 1, 2)
+
+
+def test_distant_rows_remain_separate() -> None:
+    """필요 변수: 멀리 떨어진 두 행. 작동 원리: 행 사이 연결 조건이 없으면 두 셀을 유지한다."""
+    strokes = [
+        Stroke(0, ((10, 20), (40, 20))),
+        Stroke(1, ((10, 180), (40, 180))),
+    ]
+
+    grids = build_formula_grids(strokes)
+
+    assert len(grids) == 2
+
+
+def test_parser_enforces_total_point_cap() -> None:
+    """필요 변수: 작은 점 상한과 두 획 payload. 작동 원리: 상한을 넘는 획을 받지 않는지 검증한다."""
+    payload = [
+        {"stroke_id": 0, "points": [{"x": 0, "y": 0}, {"x": 1, "y": 1}]},
+        {"stroke_id": 1, "points": [{"x": 2, "y": 2}, {"x": 3, "y": 3}]},
+    ]
+
+    strokes = parse_writing_events(payload, GridConfig(max_total_points=2))
+
+    assert [stroke.stroke_id for stroke in strokes] == [0]
+
+
+def test_renderer_returns_one_rgb_image_per_grid() -> None:
+    """필요 변수: 캔버스·두 행. 작동 원리: 각 셀에 대응하는 RGB 이미지가 생성되는지 검증한다."""
+    strokes = [
+        Stroke(0, ((10, 20), (40, 20))),
+        Stroke(1, ((10, 180), (40, 180))),
+    ]
+    grids = build_formula_grids(strokes)
+
+    images = render_grid_images(Image.new("RGB", (100, 220), "white"), strokes, grids)
+
+    assert len(images) == len(grids) == 2
+    assert all(image.mode == "RGB" for image in images)
+