docs

Author: latentCall145

MANUAL.md

@@ -0,0 +1,130 @@
+# Manual
+
+This viewer shows paired hardware and logical layouts and lets you inspect how cells map between them.
+
+## Selection
+
+- `Left click + drag`: create a new selection.
+- `Shift + left click + drag`: add cells to the current selection.
+- `Ctrl + left click + drag`: remove cells from the current selection.
+- `Click` on empty space: clear the current selection.
+
+Selections are paired across hardware and logical layouts. Selecting cells in one view highlights the mapped cells in the other.
+
+Videos:
+
+- [Left click + drag](./docs/manual-vids/0-lclick-drag.mp4)
+- [Shift + left click + drag](./docs/manual-vids/1-shift-lclick-drag.mp4)
+- [Ctrl + left click + drag](./docs/manual-vids/2-ctrl-lclick-drag.mp4)
+- [Click empty space to deselect](./docs/manual-vids/3-lclick-out-bounds.mp4)
+
+## Inspector
+
+The `Inspector` widget shows information for the cell under the cursor:
+
+- hovered tensor
+- hardware coordinate
+- logical coordinate
+- hardware coordinate in binary
+- logical coordinate in binary
+- tensor shape
+- rank
+
+For linear-layout tabs, `Hardware Coord` is the `T/W/R` coordinate and `Logical Coord` is the `A/B/...` coordinate.
+
+Video:
+
+- [Inspector](./docs/manual-vids/4-inspector.mp4)
+
+## Show Matrix
+
+`Show Matrix` displays the current rendered layout matrix.
+
+- It is tab-specific.
+- It updates when the layout is rendered.
+- Row and column labels are color-coded to match the dimension-line colors.
+
+Video:
+
+- [Show Matrix](./docs/manual-vids/5-show-matrix.mp4)
+
+## Tabs
+
+- Click a tab to switch layouts.
+- `Add New Tab` duplicates the current tab as a new editable tab.
+- Click the `x` on a tab to close it.
+- Each tab stores its own layout, slicing state, HSL settings, and cell-text settings.
+
+Video:
+
+- [Tabs](./docs/manual-vids/6-tabs.mp4)
+
+## Slicing
+
+Use the `Tensor View` widget to change the active tensor view and slice hidden axes.
+
+- Edit the `View String` to permute or hide axes.
+- Use the slice sliders to move through hidden-axis indices.
+
+For paired linear-layout tabs, slicing one tensor filters the corresponding visible cells in the other tensor as well.
+
+Video:
+
+- [Slicing](./docs/manual-vids/7-slicing.mp4)
+
+## HSL Coloring
+
+Use the `HSL Mapping` widget to control the cell colors.
+
+- Drag the `H`, `S`, and `L` chips to swap which axis drives each channel.
+- Edit the start/end numeric fields for each channel range.
+- Click `Recolor Layout` to apply the updated coloring.
+
+The mapping is per tab.
+
+Video:
+
+- [HSL coloring](./docs/manual-vids/8-hsl-coloring.mp4)
+
+## Cell Text
+
+Use the `Cell Text` widget to overlay hardware ids on cells.
+
+- `Warp Id`
+- `Thread Id`
+- `Register Id`
+
+Text appears on both the hardware and logical layouts. Logical cells show the mapped hardware ids for the corresponding element.
+
+Video:
+
+- [Cell text](./docs/manual-vids/9-cell-text.mp4)
+
+## Display Toggles
+
+From the `Display` menu:
+
+- `Toggle Block Gaps`: show or hide spacing between higher-level layout blocks.
+- `Toggle Dimension Lines`: show or hide tensor outlines, dimension guides, and axis labels.
+
+These can also be changed from the sidebar widgets where available.
+
+Video:
+
+- [Display toggles](./docs/manual-vids/10-display-toggles.mp4)
+
+## Save
+
+Use `File -> Save as SVG` to export the current 2D view.
+
+- Shortcut: `Ctrl+S`
+- The SVG includes tensor names, dimension lines, axis labels, cell colors, and supported overlays visible in the current 2D view.
+
+Video:
+
+- [Save as SVG](./docs/manual-vids/11-save.mp4)
+
+## Notes
+
+- GitHub Pages serves the static frontend only.
+- The local Python demo can additionally serve `/api/session.json` and tensor payload files.

README.md

@@ -1,6 +1,14 @@
 # linear-layout-viz
 
-Minimal wrapper repo for experiments that build on the local [`tensor-viz`](./tensor-viz) project.
+![Cover](./assets/cover.png)
+
+A visualizer for Triton linear layouts.
+- Website: https://deep-learning-profiling-tools.github.io/linear-layout-viz/
+  - There might be problems with sidebar spacing with Firefox (I use Librewolf so that's why I'm not sure if it's a Firefox or Librewolf problem). Should work fine on Chromium.
+- Paper: https://arxiv.org/pdf/2505.23819
+
+See [MANUAL.md](./MANUAL.md) for the viewer interaction guide.
+See [docs/sample-svgs/](./docs/sample-svgs/README.md) for example exported SVGs.
 
 ## Structure
 
@@ -18,12 +26,6 @@ pip install -e .
 npm run build
 ```
 
-## GitHub Pages
-
-The repo now includes [`.github/workflows/deploy-pages.yml`](./.github/workflows/deploy-pages.yml), which builds the static Vite demo from `tensor-viz/packages/viewer-demo` and publishes it to GitHub Pages.
-
-Important limitation: GitHub Pages is static-only. The public site can render browser-side linear layouts from the new sidebar and still open local `.npy` files, but it cannot run the Python `tensor_viz.viz(...)` server or serve `/api/session.json`.
-
 ### One-time GitHub setup
 
 1. Push this repo, including the submodule pointer you want Pages to build.
@@ -41,26 +43,8 @@ npm run build --workspace @tensor-viz/viewer-demo
 
 The built site is written to `tensor-viz/packages/viewer-demo/dist`.
 
-### Linear Layout Sidebar Schema
-
-The public site's layout editor accepts JSON shaped like Triton's `LinearLayout.from_bases(...)` call:
-
-```json
-{
-  "name": "Blocked Layout",
-  "bases": [
-    ["warp", [[0, 8], [0, 16]]],
-    ["thread", [[4, 0], [8, 0], [0, 1], [0, 2], [0, 4]]],
-    ["register", [[1, 0], [2, 0]]]
-  ],
-  "out_dims": ["x", "y"]
-}
-```
-
-`out_dims` can also be written as `[name, size]` pairs when you want to pin the output shape explicitly.
-
-## Notes
+## Usage
 
-- the submodule points at `https://github.com/Deep-Learning-Profiling-Tools/tensor-viz`
-- the wrapper repo builds whatever committed `tensor-viz` revision the submodule pointer references
-- if you want Pages to include newer `tensor-viz` changes, commit them in `tensor-viz` first and then update the submodule pointer here
+- For day-to-day viewer usage, see [MANUAL.md](./MANUAL.md).
+- The manual covers selection, inspector, matrix view, tabs, slicing, HSL coloring, cell text, display toggles, and saving SVG output.
+- For example exports, see [docs/sample-svgs/](./docs/sample-svgs/README.md).