Skip to content

Commit f062ffd

Browse files
imikejacksonimikejackson
committed
Add filter doc reference files: upstream-filter-sources, filter-figure-style
Reference material extracted from the vv-filter-documentation skill so the lookup table can be grown by separate agents and the figure style guide is versioned with the project. - docs/upstream-filter-sources.md: input array → producing filter table with conventions for growing the table and a stub for future graph representation. - docs/filter-figure-style.md: canonical font, color palette, callout box, file format, and naming conventions for filter doc figures.
1 parent d2b8f16 commit f062ffd

2 files changed

Lines changed: 182 additions & 0 deletions

File tree

‎docs/filter-figure-style.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Filter Documentation Figure Style Guide
2+
3+
Visual style and file conventions for figures generated to support filter documentation. Established during the documentation review project (batches 1+) so that figures across plugins look consistent. Reference palette: `docs/style_palette_final.svg` in this repo.
4+
5+
## When to Add a Figure
6+
7+
**Add a figure when:**
8+
9+
- The filter operates on spatial data and the spatial relationship matters (kernels, neighborhoods, alignment, neighbor counts).
10+
- The filter has a multi-step algorithm that benefits from a flowchart or sequence diagram.
11+
- The filter transforms data in a way easier to show than describe (orientation conversions, geometry operations).
12+
- The filter has parameters whose effect is non-obvious (kernel radius, dilation iterations, coordination number).
13+
14+
**Skip a figure when:**
15+
16+
- The filter performs a simple mathematical operation (radians-to-degrees, threshold).
17+
- The filter is a basic I/O operation (read file, write file).
18+
- The filter's behavior is fully captured by its parameter names (delete data, rename data).
19+
20+
## Font
21+
22+
```
23+
'Segoe UI', 'Helvetica Neue', Arial, sans-serif
24+
```
25+
26+
| Element | Size | Weight | Color |
27+
|---------|------|--------|-------|
28+
| Figure title | 17-18px | Bold (700) | #2C3E50 |
29+
| Section heading | 14px | Semibold (600) | #2C3E50 |
30+
| Body text | 13px | Regular (400) | #555555 |
31+
| Captions / notes | 11px | Italic | #888888 |
32+
33+
## Color Palette
34+
35+
### Primary (Diagram Elements)
36+
37+
| Role | Color | Hex | Usage |
38+
|------|-------|-----|-------|
39+
| Focus | Dark Blue | #2874A6 | Center cell, primary element, section headers |
40+
| Active | Light Blue | #AED6F1 | Kernel neighbors, included elements |
41+
| Inactive | Light Gray | #E8ECF0 | Outside kernel, excluded elements |
42+
43+
### Semantic Accents
44+
45+
| Role | Color | Hex | Usage |
46+
|------|-------|-----|-------|
47+
| Danger / Warning | Red | #E74C3C | Thread-safety warnings, invalid approaches, common mistakes |
48+
| Good / Correct | Green | #27AE60 | Recommended approaches, valid results, correct measurements |
49+
| Annotation | Purple | #8E44AD | Brackets, dimensions, labels, measurements |
50+
| Tip / Highlight | Amber | #E67E22 | Tips, parameters of interest, optional recommendations |
51+
52+
### Supporting
53+
54+
| Role | Color | Hex | Usage |
55+
|------|-------|-----|-------|
56+
| Primary text | Dark Slate | #2C3E50 | Headings, primary labels |
57+
| Secondary text | Medium Gray | #5D6D7E | Secondary labels, descriptions |
58+
| Card background | White | #FFFFFF | Figure card background |
59+
| Formula background | Pale Blue | #EBF5FB | Formula / equation highlight boxes |
60+
| Warning background | Pale Red | #FDEDEC | Warning callout box fill |
61+
| Success background | Pale Green | #EAFAF1 | Success callout box fill |
62+
| Annotation background | Pale Purple | #F4ECF7 | Note callout box fill |
63+
| Tip background | Pale Amber | #FEF5E7 | Tip callout box fill |
64+
| Page background | Off-white | #F0F2F5 | Outer page fill (when used) |
65+
66+
## Callout Boxes
67+
68+
Four semantic callout box types are available:
69+
70+
- **Warning (Red)** — `!` icon, #FDEDEC background, #E74C3C border. For dangers and things to watch out for.
71+
- **Good / Correct (Green)** — checkmark icon, #EAFAF1 background, #27AE60 border. For recommended approaches.
72+
- **Note (Purple)** — `i` icon, #F4ECF7 background, #8E44AD border. For general annotations and clarifications.
73+
- **Tip (Amber)** — star icon, #FEF5E7 background, #E67E22 border. For tips and highlights.
74+
75+
## Section Headers
76+
77+
Colored bars with white text, using the semantic color that best fits the section content. Default to blue (#2874A6) for neutral sections.
78+
79+
## File Format and Naming
80+
81+
- **Author as SVG.** Hand-write or generate the source.
82+
- **Convert to PNG at 2x resolution** using `rsvg-convert -z 2 source.svg -o source.png`. The 2x scale provides a clean appearance on high-DPI displays.
83+
- **Keep both SVG and PNG** in the plugin's `<plugin>/docs/Images/` directory (e.g., `src/Plugins/OrientationAnalysis/docs/Images/`).
84+
- **Reference the PNG** in the filter documentation markdown, not the SVG.
85+
- **Naming convention:** `<FilterName>_<Description>.png`. Examples:
86+
- `ComputeKernelAvgMisorientations_1D_Radius1.png`
87+
- `ComputeAvgCAxes_HexagonalCAxis.png`
88+
- `ComputeSchmids_SchmidFactor.png`
89+
90+
## Markdown Reference Pattern
91+
92+
Use the figure caption as the alt text and as a short Fig. N descriptor:
93+
94+
```markdown
95+
![Fig. 1: The geometric relationship between the tensile axis, slip plane, and slip direction that defines the Schmid factor.](Images/ComputeSchmids_SchmidFactor.png)
96+
```
97+
98+
For paired before/after figures, use a 2-column table:
99+
100+
```markdown
101+
| Before | After |
102+
|----------------------------------|----------------------------------|
103+
| ![](Images/ExampleFilter_1.png) | ![](Images/ExampleFilter_2.png) |
104+
```
105+
106+
## Reference SVGs
107+
108+
- `docs/style_palette_final.svg` — canonical color palette, font, and callout box styles. Open in any SVG viewer to copy colors.
109+
- Existing finished figures in `src/Plugins/OrientationAnalysis/docs/Images/` (especially `ComputeKernelAvgMisorientations_*.svg` and `ComputeAvgCAxes_HexagonalCAxis.svg`) are good reference templates to fork from.

‎docs/upstream-filter-sources.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Upstream Filter Sources
2+
3+
Lookup table mapping common input arrays to the filter(s) that produce them. Used when writing the **Required Input Sources** section of a filter's documentation (see the `vv-filter-documentation` skill for the convention).
4+
5+
This file is intended to be grown over time. As more filters are documented or new filters are added, append rows. The longer-term goal is to derive a dependency graph from this data so that pipeline order constraints can be visualized.
6+
7+
## How To Use
8+
9+
When documenting a filter that requires array X, look up X in the table below and link to the producing filter from your Required Input Sources section using MyST link syntax:
10+
11+
```markdown
12+
- **X** -- produced by [Producer Human Name](ProducerFilter.md).
13+
```
14+
15+
For arrays produced by EBSD readers (Cell Quaternions, Cell Phases, ensemble Crystal Structures), name the typical readers explicitly rather than picking one:
16+
17+
```markdown
18+
- **Cell Quaternions** -- typically read from EBSD data via [Read H5EBSD](ReadH5EbsdFilter.md), [Read CTF Data](ReadCtfDataFilter.md), or [Read ANG Data](ReadAngDataFilter.md); can also be produced from Euler angles by [Convert Orientations](ConvertOrientationsFilter.md).
19+
```
20+
21+
## Conventions for Growing This Table
22+
23+
- **One row per array, multiple producers comma-separated** in the Producer column when the array can come from several filters.
24+
- **Plugin column** lists where the *producer* lives, not where the consuming filter lives. This drives the relative-path direction of MyST links.
25+
- **Cross-plugin links** must use `../OtherPlugin/FilterFile.md`. Within-plugin links use `FilterFile.md` only.
26+
- **Filter names match `humanName()`** in the .cpp, not the file name. The link target file is always `<PascalCaseFilterName>Filter.md`.
27+
- **Notes column** (optional) for caveats: ensemble-level vs feature-level vs cell-level, optional inputs, mode dependencies (e.g., "only when *Find Coherence* is enabled").
28+
29+
## Lookup Table
30+
31+
| Input Array | Producer (humanName) | Plugin | Notes |
32+
|---|---|---|---|
33+
| Cell Quaternions | Read H5EBSD / Read CTF Data / Read ANG Data / Convert Orientations | OrientationAnalysis | From EBSD readers, or computed from Euler angles |
34+
| Cell Eulers | Same EBSD readers | OrientationAnalysis | Bunge convention Z-X-Z |
35+
| Cell Phases | Same EBSD readers | OrientationAnalysis | Read alongside quaternions |
36+
| Crystal Structures | Same EBSD readers / Create Ensemble Info | OrientationAnalysis | Ensemble-level array |
37+
| Cell Feature Ids | Segment Features (Misorientation) | OrientationAnalysis | Misorientation-based grain segmentation |
38+
| Cell Feature Ids | Segment Features (C-Axis Misalignment) | OrientationAnalysis | Hexagonal-only |
39+
| Cell Feature Ids | Segment Features (Scalar) | SimplnxCore | Scalar-based segmentation |
40+
| Cell Parent Ids | Merge Twins | OrientationAnalysis | Cell-level grouping into parent grains |
41+
| Feature Parent Ids | Merge Twins | OrientationAnalysis | Feature-level mapping |
42+
| Feature Phases | Compute Feature Phases | SimplnxCore | Feature-level (one phase per feature) |
43+
| Feature Phases (Binary) | Compute Feature Phases (Binary) | SimplnxCore | Two-phase classification |
44+
| Average Quaternions | Compute Average Orientations | OrientationAnalysis | Per-feature average orientation |
45+
| Average Euler Angles | Compute Average Orientations | OrientationAnalysis | Bunge convention Z-X-Z |
46+
| Average C-Axes | Compute Average C-Axis Orientations | OrientationAnalysis | Hexagonal-only |
47+
| Feature Centroids | Compute Feature Centroids | SimplnxCore | Cell-of-mass per feature |
48+
| Feature Equivalent Diameters | Compute Feature Sizes | SimplnxCore | Diameter of equal-volume sphere |
49+
| Feature Num. Cells (NumElements) | Compute Feature Sizes | SimplnxCore | Cell count per feature |
50+
| Feature Volumes | Compute Feature Sizes | SimplnxCore | Physical volume |
51+
| Surface Features | Compute Surface Features | SimplnxCore | Boolean per feature |
52+
| Surface Features | Compute Feature Neighbors | SimplnxCore | Optional output (enable *Store Surface Features Array*) |
53+
| Biased Features | Compute Biased Features (Bounding Box) | SimplnxCore | Boolean per feature |
54+
| Number of Neighbors | Compute Feature Neighbors | SimplnxCore | Count per feature |
55+
| Contiguous Neighbor List | Compute Feature Neighbors | SimplnxCore | NeighborList of contiguous Feature Ids |
56+
| Shared Surface Area List | Compute Feature Neighbors | SimplnxCore | NeighborList in cell-face-count units |
57+
| Boundary Cells | Compute Feature Neighbors | SimplnxCore | Optional output (enable *Store Boundary Cells Array*) |
58+
| Neighborhoods Neighbor List | Compute Feature Neighborhoods | SimplnxCore | Sphere-radius-based neighbor list |
59+
| Mask | Multi-Threshold Objects | SimplnxCore | Boolean per cell |
60+
| Boundary Euclidean Distances | Compute Euclidean Distance Map | SimplnxCore | Cell-level distance to nearest boundary |
61+
| Triangle Geometry | Quick Surface Mesh | SimplnxCore | Surface mesh from Feature Ids |
62+
| Face Labels | Quick Surface Mesh | SimplnxCore | Per-face Feature ID pair (2-component) |
63+
| Face Normals | Compute Triangle Normals | SimplnxCore | 3-component, on triangle face data |
64+
| Face Areas | Compute Triangle Areas | SimplnxCore | Single-component, on triangle face data |
65+
| Node Types | Quick Surface Mesh | SimplnxCore | Per-vertex node classification |
66+
| Cell Shifts Array (alignment) | Align Sections (Feature Centroid) | SimplnxCore | Output of any Align Sections * filter |
67+
| Cell Shifts Array (alignment) | Align Sections (Misorientation) | OrientationAnalysis | |
68+
| Cell Shifts Array (alignment) | Align Sections (Mutual Information) | OrientationAnalysis | |
69+
| Confidence Index / Image Quality | Read H5EBSD / Read CTF Data / Read ANG Data | OrientationAnalysis | Per-cell scalar quality metric |
70+
71+
## Future: Graph Representation
72+
73+
The lookup table is naturally a directed dependency graph: each row is an edge from a producer filter to the input-array node. A separate downstream effort may convert this into a graph (DOT, Mermaid, or networked JSON) to support pipeline-order checking, "what would I need to run before X?" queries, and visual dependency maps. Keep that future use in mind when adding rows -- be precise about producer humanName so the data is machine-parseable.

0 commit comments

Comments
 (0)