docs: refresh README for 2.1.0

.github/ISSUE_TEMPLATE/material-correction.yml

@@ -0,0 +1,44 @@
+name: Material data correction
+description: Report an incorrect property value or missing data
+labels: ["data-correction"]
+body:
+  - type: input
+    id: material
+    attributes:
+      label: Material
+      description: Which material has the issue
+      placeholder: e.g. stainless.s316L, aluminum.a6061
+    validations:
+      required: true
+
+  - type: input
+    id: property
+    attributes:
+      label: Property
+      description: Which property is wrong or missing
+      placeholder: e.g. density, yield_strength, thermal_conductivity
+    validations:
+      required: true
+
+  - type: input
+    id: current_value
+    attributes:
+      label: Current value (if wrong)
+      placeholder: e.g. 8.0 g/cm³
+
+  - type: input
+    id: correct_value
+    attributes:
+      label: Correct value
+      placeholder: e.g. 7.99 g/cm³
+    validations:
+      required: true
+
+  - type: input
+    id: source
+    attributes:
+      label: Source / reference
+      description: Where does the correct value come from?
+      placeholder: e.g. ASM Handbook Vol. 2, MatWeb, manufacturer datasheet URL
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/material-request.yml

@@ -0,0 +1,65 @@
+name: Material request
+description: Request a new material to be added to the library
+labels: ["material-request"]
+body:
+  - type: input
+    id: material_name
+    attributes:
+      label: Material name
+      description: Common name or trade name
+      placeholder: e.g. Inconel 718, Sapphire, Carbon Fiber T300
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      options:
+        - Metal / Alloy
+        - Ceramic
+        - Plastic / Polymer
+        - Scintillator / Detector
+        - Glass
+        - Composite
+        - Electronics
+        - Liquid
+        - Gas
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: properties
+    attributes:
+      label: Known properties
+      description: |
+        Any values you already know. Don't worry about completeness —
+        we'll fill in the rest from datasheets / literature.
+      placeholder: |
+        Density: 8.19 g/cm³
+        Yield strength: 1034 MPa
+        Melting point: 1260 °C
+        Composition: Ni 52%, Cr 19%, Fe 18%, Nb 5%, Mo 3%
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use case
+      description: What are you using this material for? Helps us prioritize.
+      placeholder: e.g. PET scanner shielding, 3D printed bracket, Geant4 simulation
+
+  - type: input
+    id: datasheet_url
+    attributes:
+      label: Datasheet or reference URL (optional)
+      placeholder: https://www.matweb.com/...
+
+  - type: textarea
+    id: appearance
+    attributes:
+      label: Visual appearance (optional)
+      description: |
+        If you need PBR textures, describe the finish. We'll try to
+        match from mat-vis's texture library.
+      placeholder: e.g. brushed finish, polished mirror, matte black anodized

.github/workflows/catalog.yml

@@ -0,0 +1,30 @@
+name: Update catalog
+
+on:
+  push:
+    branches: [dev]
+    paths: ["src/pymat/data/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  catalog:
+    name: Regenerate material catalog
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[dev]'
+      - run: python scripts/generate_catalog.py --skip-thumbnails
+      - uses: peter-evans/create-pull-request@v7
+        with:
+          title: "docs: regenerate material catalog"
+          commit-message: "docs: regenerate catalog from TOML data"
+          branch: docs/catalog-update
+          add-paths: docs/catalog/
+          delete-branch: true

.github/workflows/enrich-vis.yml

@@ -0,0 +1,45 @@
+name: Propose vis mappings
+
+on:
+  repository_dispatch:
+    types: [mat-vis-release]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  enrich:
+    name: Auto-propose vis mappings
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[dev]'
+      - run: python scripts/enrich_vis.py -o /tmp/proposed_vis.toml
+      - name: Check for proposals
+        id: check
+        run: |
+          if [ -s /tmp/proposed_vis.toml ]; then
+            echo "has_proposals=true" >> "$GITHUB_OUTPUT"
+            echo "Proposed vis mappings:"
+            cat /tmp/proposed_vis.toml
+          else
+            echo "has_proposals=false" >> "$GITHUB_OUTPUT"
+            echo "No new mappings to propose"
+          fi
+      - uses: peter-evans/create-pull-request@v7
+        if: steps.check.outputs.has_proposals == 'true'
+        with:
+          title: "chore: update vis mappings from mat-vis"
+          commit-message: "chore: auto-proposed vis mappings"
+          branch: chore/enrich-vis
+          body: |
+            Auto-generated vis mapping proposals from mat-vis index.
+            Review each material's suggested appearance match before merging.
+
+            Proposed mappings are in the commit diff.
+          delete-branch: true

.gitignore

@@ -223,3 +223,4 @@ justfile.local
 
 # Cursor local config
 .cursor/
+tests/visual_output/

CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing to mat (py-materials)
+
+## Ways to contribute
+
+### Request a material
+
+Don't have the data? [Open a material request][request] — tell us
+what you need and why. We'll source the properties from literature
+and datasheets.
+
+### Add a material
+
+Have the data? Open a PR adding a TOML entry. Here's the template:
+
+```toml
+# src/pymat/data/<category>.toml
+# Add under the appropriate category file (metals.toml, plastics.toml, etc.)
+
+[my_material]
+name = "My Material Name"
+formula = "Fe3O4"                    # optional — chemical formula
+composition = {Fe = 0.72, O = 0.28}  # optional — element mass fractions
+
+[my_material.mechanical]
+density_value = 5.17
+density_unit = "g/cm^3"
+youngs_modulus_value = 200           # optional
+youngs_modulus_unit = "GPa"
+
+[my_material.thermal]
+melting_point_value = 1597           # optional
+melting_point_unit = "degC"
+
+[my_material.pbr]
+base_color = [0.1, 0.1, 0.1, 1.0]   # RGBA, 0-1
+metallic = 0.8                        # 0 = dielectric, 1 = metal
+roughness = 0.5                       # 0 = glossy, 1 = rough
+
+# Visual appearance mapping (optional — mat-vis must have matching textures)
+[my_material.vis]
+default = "natural"
+
+[my_material.vis.finishes]
+natural = "ambientcg/Metal_SomeID"    # mat-vis source ID
+```
+
+#### What's required
+
+- `name` — human-readable
+- `density` — in `g/cm³` (needed for `compute_mass()`)
+- `base_color`, `metallic`, `roughness` — for rendering
+
+Everything else is optional. More data is better, but partial
+entries are welcome — we can enrich later.
+
+#### Hierarchy
+
+Materials support parent → child hierarchy:
+
+```toml
+[aluminum]
+name = "Aluminum"
+# base properties...
+
+[aluminum.a6061]
+name = "Aluminum 6061-T6"
+grade = "6061"
+temper = "T6"
+# only overrides — inherits everything from parent
+```
+
+### Fix a value
+
+Spotted an error? [Open a correction issue][correction] with the
+correct value and a source citation. Or open a PR directly —
+edit the TOML, cite your source in the commit message.
+
+### Improve the code
+
+See the [open issues][issues] for bugs, features, and
+refactoring tasks. The standard workflow:
+
+1. Fork the repo
+2. Create a branch from `dev`
+3. Make your changes
+4. Run tests: `pytest tests/ -v`
+5. Run linter: `ruff check src/ tests/`
+6. Open a PR against `dev`
+
+## Data quality
+
+- **Cite your sources.** Every property value should be traceable
+  to a datasheet, handbook, or paper. Include the reference in the
+  commit message or PR description.
+- **Use SI-compatible units** with the `_value` / `_unit` suffix
+  pattern (e.g. `density_value = 8.0`, `density_unit = "g/cm^3"`).
+- **Don't fabricate values.** If a property isn't known, leave it
+  out. `None` is better than a guess.
+- **PBR values can be approximate.** Rendering properties are
+  visual, not physical measurements. Matching "looks like steel"
+  is fine.
+
+## Visual appearance (vis)
+
+Materials can optionally link to [mat-vis][mat-vis] textures for
+PBR rendering. To find matching textures:
+
+```python
+from pymat import vis
+vis.search(category="metal", roughness=0.3)
+```
+
+Add the match to the `[vis]` section of the TOML. If you're
+unsure, leave it out — the `enrich_vis.py` script proposes
+matches automatically.
+
+[request]: https://github.com/MorePET/mat/issues/new?template=material-request.yml
+[correction]: https://github.com/MorePET/mat/issues/new?template=material-correction.yml
+[issues]: https://github.com/MorePET/mat/issues
+[mat-vis]: https://github.com/MorePET/mat-vis