Metadata-Version: 2.4
Name: codechu-treeviz
Version: 0.1.0
Summary: Squarified treemap + sunburst layout algorithms for hierarchical data. Pure logic, no GUI dependency.
Author: Codechu
License: MIT License
        
        Copyright (c) 2026 Codechu
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/codechu/treeviz-py
Project-URL: Source, https://github.com/codechu/treeviz-py
Project-URL: Issues, https://github.com/codechu/treeviz-py/issues
Keywords: treemap,sunburst,visualization,hierarchical-data,squarified
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# codechu-treeviz

Squarified treemap + sunburst layout algorithms for hierarchical data.
Pure Python, no GUI dependency — gives you rectangles and arcs; you
render them with whatever toolkit (Cairo, SVG, Matplotlib, browser canvas).

```bash
pip install codechu-treeviz
```

## What it gives you

- **Squarified treemap** layout — Bruls/Huijsen/van Wijk algorithm, aspect-ratio optimized
- **Sunburst** layout — circular hierarchical chart with concentric rings
- **TreeNode** builder — turn a `(path, size)` list into a hierarchical tree
- **Hit testing** — given (x, y), find the node at that position
- **"Other" bundling** — small slivers grouped into a single "(N items)" bucket
- **Color palette** — perceptually balanced fill colors
- Pure stdlib + Python `math`, zero deps

## Example

```python
from codechu_treeviz import build_tree, layout_treemap, layout_sunburst, hit_test

# 1. Build a tree from flat (path, size) records
items = [
    ("/home/user/Documents", 5_000_000_000),
    ("/home/user/Pictures",  2_000_000_000),
    ("/home/user/.cache",    1_200_000_000),
    ("/var/log",               300_000_000),
]
root = build_tree(items)

# 2. Treemap layout — produces rectangles for each node
rects = layout_treemap(root, width=800, height=600, min_frac=0.005)
for r in rects:
    # r.x, r.y, r.w, r.h, r.node
    print(r.node.label, (r.x, r.y, r.w, r.h))

# 3. Sunburst layout — produces arc segments
arcs = layout_sunburst(root, cx=400, cy=300, max_radius=250)
for a in arcs:
    # a.cx, a.cy, a.r1, a.r2, a.a1, a.a2, a.node
    print(a.node.label, "ring", a.a1, "→", a.a2)

# 4. Hit test
from codechu_treeviz import hit_test
node = hit_test(rects, x=120, y=80)  # which rect at (120,80)?
```

## API surface

| Function / class | Purpose |
|---|---|
| `build_tree(items, progress=None, cancel=None)` | Build TreeNode from flat (path, size) list |
| `layout_treemap(node, width, height, min_frac=0.005)` | Squarified rect layout |
| `layout_sunburst(node, cx, cy, max_radius, ...)` | Concentric-ring arc layout |
| `hit_test(rects, x, y)` | Find treemap rect at coords |
| `sunburst_hit_test(arcs, x, y, cx, cy)` | Find sunburst arc at coords |
| `TreeNode` | Hierarchical node (children, total_size, label) |
| `TreemapStrategy` / `SunburstStrategy` | OOP wrapper (optional, for plugin pattern) |
| `node_color(node)` | Stable color from node identity |
| `is_hash_like(s)` | Heuristic: is this a hash-like name (cache key vs human label) |

## Design

- **No rendering** — algorithms produce geometry; rendering is your job
  (Cairo, SVG, PNG via Pillow, browser canvas via JSON over HTTP, etc.)
- **No GUI dependency** — `import codechu_treeviz` works without GTK/Qt/Tk
- **Cancel + progress** support in `build_tree` for long inputs
- **Bounded depth** (`TREEMAP_MAX_DEPTH = 40`) protects against pathological nesting

## Use cases

- Disk usage visualizer (the original)
- Source-code size / dependency tree explorer
- Package size analyzer (npm, PyPI, Cargo)
- Time-tracking dashboard (project / task / subtask hierarchy)
- Any "where did the bytes / hours / records go?" question

## License

MIT — see [LICENSE](LICENSE).

Part of [Codechu](https://github.com/codechu).
