Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .github/skills/glossary-references/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Every glossary sidebar reference uses Quarto's native `{.column-margin}` contain
::: {.column-margin}
**<Term Name> ($<Symbol>$ hold if applicable)**
<One to two concise sentences defining the concept, its physical meaning, and standard units or sign convention>.
[<Domain> Glossary &rarr;](resources/<domain>-glossary.qmd#<section-anchor>)
[<Domain> Glossary &rarr;](resources/<domain>/<domain>-glossary.qmd#<section-anchor>)
:::
```

Expand All @@ -34,7 +34,7 @@ A lens is considered a **thin lens** when its axial thickness is negligible comp
::: {.column-margin}
**Radius of curvature ($R$)**
Linear distance from the surface vertex to the center of the sphere of curvature.
[Optics Glossary &rarr;](resources/optics-glossary.qmd#sec-glossary-surfaces)
[Optics Glossary &rarr;](resources/optics/optics-glossary.qmd#sec-glossary-surfaces)
:::
```

Expand Down Expand Up @@ -71,10 +71,10 @@ When linking, use relative paths from `chapters/`:

| Domain | Resource File Path (relative to `chapters/`) | Primary Topics Covered |
|:-------|:---------------------------------------------|:-----------------------|
| **Optics** | `resources/optics-glossary.qmd` | Surface geometry ($R, C$), focal length ($f$), conjugate image distance ($d_i$), sensor distance ($d_s$), circle of confusion |
| **Sensors** | `resources/sensors-glossary.qmd` | Pixel pitch, fill factor, quantum efficiency (QE), full well capacity (FWC), read noise, dynamic range (DR), conversion gain |
| **Human Vision** | `resources/human-glossary.qmd` | Visual angle, cycles per degree (cpd), luminance vs. illuminance, photopic/scotopic, DVA, cone mosaics |
| **Displays** | `resources/displays-glossary.qmd` | Luminance (nits/$\text{cd/m}^2$), color gamut, subpixel layout, display gamma ($\gamma$), refresh rate, viewing angle |
| **Optics** | `resources/optics/optics-glossary.qmd` | Surface geometry ($R, C$), focal length ($f$), conjugate image distance ($d_i$), sensor distance ($d_s$), circle of confusion |
| **Sensors** | `resources/sensors/sensors-glossary.qmd` | Pixel pitch, fill factor, quantum efficiency (QE), full well capacity (FWC), read noise, dynamic range (DR), conversion gain |
| **Human Vision** | `resources/human/human-glossary.qmd` | Visual angle, cycles per degree (cpd), luminance vs. illuminance, photopic/scotopic, DVA, cone mosaics |
| **Displays** | `resources/displays/displays-glossary.qmd` | Luminance (nits/$\text{cd/m}^2$), color gamut, subpixel layout, display gamma ($\gamma$), refresh rate, viewing angle |

---

Expand Down
43 changes: 38 additions & 5 deletions .github/skills/interactive-figures/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,55 @@
---
name: interactive-figures
description: Create, modify, embed, format, or diagnose client-side interactive figures using Observable JS (OJS) or self-contained HTML/Canvas 3D iframe visualizations in Quarto book chapters.
description: Create, modify, embed, format, or diagnose client-side interactive figures using self-contained HTML/SVG/JS includes, Observable JS (OJS), or Canvas 3D iframe visualizations in Quarto book chapters.
---

# Interactive Figures with Quarto

## Summary
## Summary & General Requirement

This project embeds interactive, client-side scientific visualizations and simulations directly into book chapters. All computation runs entirely in the reader's web browser without a server-side computational kernel, using **two complementary patterns**:
This project embeds interactive, client-side scientific visualizations and simulations directly into book chapters. All computation runs entirely in the reader's web browser without a server-side computational kernel.

1. **Pattern A — Observable JS (OJS) & Observable Plot (Default for 2D):** Use for analytical equations, standard 2D scientific curves, and reactive parameter sweeps with sliders/inputs. Shares page typography and responsive width natively with no `_quarto.yml` resource entries needed.
> **General Requirement — Keep Chapter `.qmd` Files Clean via Includes:**
> Do **not** inline long interactive HTML, CSS, JavaScript, or OJS visualization code directly inside a chapter `.qmd` file. Place the interactive code in a standalone file under **`chapters/includes/figures/<slug>.qmd`** (keep this directory flat—do not create subdirectories under `chapters/includes/figures/`) and embed it in the chapter with `{{< include includes/figures/<slug>.qmd >}}` inside a `::: {.content-visible when-format="html"}` block.

We use **three complementary patterns**:

1. **Pattern A — Self-Contained HTML/SVG/JS Include (` ```{=html} `, Default for 2D & Pan/Zoom):** Place a self-contained `{=html}` block (controls + SVG/Canvas/image + vanilla JS) in `chapters/includes/figures/<slug>.qmd` and include it with `{{< include includes/figures/<slug>.qmd >}}`. Works offline with zero external dependencies, requires no `_quarto.yml` resource entries, and triggers no Quarto OJS warnings.
2. **Pattern B — Self-Contained HTML / Canvas 3D (`<iframe>`):** Use for interactive 3D geometry, orbitable coordinate spaces, and custom canvas visualizations that work offline without external JS libraries or WebGL, and can also be reused standalone in lecture slides.
3. **Pattern C — Observable JS (OJS) & Observable Plot:** Optional for quick reactive 2D plots. **Caveat:** Quarto currently emits `WARN: OJS block count mismatch. Line number reporting is likely to be wrong` when `{ojs}` cells are loaded via `{{< include >}}`. Prefer **Pattern A (`{=html}`)** so the code can live cleanly in `chapters/includes/figures/<slug>.qmd` without warnings.

*(Avoid introducing heavy compiled toolchains such as WebAssembly/Rust or external charting bundles unless a specific numerical simulation genuinely hits a plain-JavaScript performance bottleneck.)*

---

## Pattern A: Observable JS (OJS) & Observable Plot (Default for Analytical Models)
## Pattern A: Self-Contained HTML/SVG/JS Include (`chapters/includes/figures/<slug>.qmd`)

Use this pattern for interactive 2D plots, parameter sweeps, and pan-and-zoom image viewers (e.g., `chapters/includes/figures/cielab-sweep-panzoom.qmd`, `chapters/includes/figures/cieluv-vs-cielab.qmd`).

### Guidelines
- Wrap all markup and script inside a single ```` ```{=html} ```` fence in `chapters/includes/figures/<slug>.qmd`.
- Scope DOM queries to a unique root element ID (e.g., `id="widget-<slug>"`) inside an IIFE `(() => { ... })();` so multiple interactive figures on the same page never collide.
- Keep all styling inline or scoped to `#widget-<slug>` so it does not leak to surrounding book prose.
- In the parent chapter `.qmd`, embed the include inside a single `::: {#fig-<label>}` container alongside a static fallback for non-HTML formats:

```markdown
::: {#fig-example-interactive}

::: {.content-visible when-format="html"}
{{< include includes/figures/example-widget.qmd >}}
:::

::: {.content-visible unless-format="html"}
![](images/<subject>/<nn-chapter>/<slug>-static.png){fig-alt="Accessible description." width="85%"}
:::

Shared figure caption explaining what the visualization shows and how to use the HTML controls.
:::
```

---

## Pattern C: Observable JS (OJS) & Observable Plot (Optional)

### Core Components
- **Observable JS (`ojs`)**: Reactive JavaScript runtime built into Quarto.
Expand Down
2 changes: 1 addition & 1 deletion .github/skills/matlab-evaluation/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,4 +101,4 @@ iePublish('~/Documents/MATLAB/isetfise/fise/02Optics/fise_diffraction.m')"
"$MATLAB" -batch "addpath(genpath('~/Documents/MATLAB/isetcam')); iePublish('fise_script.m')"
```

4. `iePublish` writes the HTML next to the source `.m` file in `isetfise/fise/`. Confirm the output landed where expected and that figures embedded correctly before updating links in `chapters/resources/code-html-links.qmd` or book chapters.
4. `iePublish` writes the HTML next to the source `.m` file in `isetfise/fise/`. Confirm the output landed where expected and that figures embedded correctly before updating links in `chapters/resources/general/code-html-links.qmd` or book chapters.
2 changes: 1 addition & 1 deletion .github/skills/reproducible-matlab/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Tutorial scripts are published to HTML using `iePublish` (from `isetcam`) and li
```
https://htmlpreview.github.io/?https://github.com/ISET/isetfise/blob/main/fise/<topic-folder>/<script>.html
```
An index of published code links is maintained in `chapters/resources/code-html-links.qmd`.
An index of published code links is maintained in `chapters/resources/general/code-html-links.qmd`.

Treat source code and its generated figures as a pair. Do not edit a generated image to change a scientific result when the appropriate change belongs in the script or live script.

Expand Down
31 changes: 19 additions & 12 deletions .github/skills/resource-authoring/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,26 +28,33 @@ A single `#` title with an explicit `#sec-resource-*` anchor label:
# Title of the Resource {#sec-resource-slug}
```

## Directory Organization

Organize resource `.qmd` files under `chapters/resources/<topic>/` by topic:
- `displays/` (e.g., `displays-glossary.qmd`)
- `general/` (e.g., `chat-index.qmd`, `code-html-links.qmd`)
- `history/` (e.g., `history-Poisson.qmd`, `history-color.qmd`, `history-linear-algebra.qmd`)
- `human/` (e.g., `human-glossary.qmd`, `human-tetrachromacy.qmd`, `PCC.qmd`)
- `lightfield/` (e.g., `lightfield-measurements.qmd`, `lightfields-wavebands.qmd`, `fractals.qmd`)
- `math/` (e.g., `math-phasors.qmd`)
- `optics/` (e.g., `optics-glossary.qmd`, `optics-diffraction.qmd`, `optics-ideal-lens.qmd`, `optics-abcd.qmd`)
- `sensors/` (e.g., `sensors-glossary.qmd`)

### 3. Work-in-Progress Callout Include
Immediately beneath the title, include the WIP callout using the appropriate relative path:
- For files directly in `chapters/resources/`:
```markdown
{{< include "../includes/WIP-callout.qmd" >}}
```
- For nested resources (e.g., `chapters/resources/Artal-2024/Artal-2024.qmd`):
```markdown
{{< include "../../includes/WIP-callout.qmd" >}}
```
Immediately beneath the title, include the WIP callout using the appropriate relative path for files inside `chapters/resources/<topic>/`:
```markdown
{{< include "../../includes/WIP-callout.qmd" >}}
```

### 4. Navigation Bar
Provide clear return paths for readers arriving from search, the sidebar, or a chapter link:
Provide clear return paths for readers arriving from search, the sidebar, or a chapter link (from `chapters/resources/<topic>/`):
- **If linked from a specific parent chapter:**
```markdown
[Return to <Chapter Title>](../<chapter-filename>.qmd) | [Return to book home](../../index.qmd)
[Return to <Chapter Title>](../../<chapter-filename>.qmd) | [Return to book home](../../../index.qmd)
```
- **If not linked from a specific chapter (general reference):**
```markdown
[Return to book home](../../index.qmd)
[Return to book home](../../../index.qmd)
```

Place the navigation bar near the top (right after the WIP callout or header) and repeat it as a footer at the bottom of the document so readers do not have to scroll all the way back up.
Expand Down
24 changes: 12 additions & 12 deletions _quarto.yml
Original file line number Diff line number Diff line change
Expand Up @@ -79,18 +79,18 @@ book:
- chapters/appendix-03-isetcam.qmd
- part: "Resources"
chapters:
- chapters/resources/optics-glossary.qmd
- chapters/resources/sensors-glossary.qmd
- chapters/resources/human-glossary.qmd
- chapters/resources/displays-glossary.qmd
- chapters/resources/lightfield-measurements.qmd
- chapters/resources/lightfields-wavebands.qmd
- chapters/resources/fractals.qmd
- chapters/resources/optics-diffraction.qmd
- chapters/resources/optics-ideal-lens.qmd
- chapters/resources/history-Poisson.qmd
- chapters/resources/history-linear-algebra.qmd
- chapters/resources/history-color.qmd
- chapters/resources/optics/optics-glossary.qmd
- chapters/resources/sensors/sensors-glossary.qmd
- chapters/resources/human/human-glossary.qmd
- chapters/resources/displays/displays-glossary.qmd
- chapters/resources/lightfield/lightfield-measurements.qmd
- chapters/resources/lightfield/lightfields-wavebands.qmd
- chapters/resources/lightfield/fractals.qmd
- chapters/resources/optics/optics-diffraction.qmd
- chapters/resources/optics/optics-ideal-lens.qmd
- chapters/resources/history/history-Poisson.qmd
- chapters/resources/history/history-linear-algebra.qmd
- chapters/resources/history/history-color.qmd
- chapters/resources/Artal-2024/Artal-2024.qmd
- chapters/references.qmd

Expand Down
2 changes: 1 addition & 1 deletion chapters/appendix-02-spaceinvariance.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ The younger faculty, who spent most of our time programming, tended to favor sta

These were spirited debates, born from a shared passion for teaching. Today, linear algebra is the language of modern computational science, from machine learning to the image systems in this book. That's why I've chosen the matrix-first approach here. Still, I often think of Ron's advice and the importance of understanding the continuous-domain theory that these discrete methods represent.

It's also worth remembering that matrix methods are not just a modern computational fad; they have a rich history stretching back nearly two centuries. If you’re interested, you can read more about the [history of these powerful ideas](resources/history-linear-algebra.qmd){target=_blank}.
It's also worth remembering that matrix methods are not just a modern computational fad; they have a rich history stretching back nearly two centuries. If you’re interested, you can read more about the [history of these powerful ideas](resources/history/history-linear-algebra.qmd){target=_blank}.
:::

## Discrete Fourier Series (DFS) {#sec-optics-fourier-series}
Expand Down
18 changes: 9 additions & 9 deletions chapters/human-04-spatial-metrics.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,21 @@ date: last-modified
{{< include "includes/WIP-callout.qmd" >}}

## Spatial metrics overview {#sec-human-metrics-overview}
How can we evaluate the design of an image system? Lord Kelvin wrote about engineering and science more generally in that crisp, British style

How can we evaluate the design of a camera? Lord Kelvin put it in that lovely style of the British upper crust
> when you can measure what you are speaking about, and express it in numbers, you know something about it; but when you cannot measure it, when you cannot express it in numbers, your knowledge is of a meagre and unsatisfactory kind (@thomson1889-presidential-address)

> when you can measure what you are speaking about, and express it in numbers, you know something about it; but when you cannot measure it, when you cannot express it in numbers, your knowledge is of a meagre and unsatisfactory kind (Popular Lectures and Addresses "Electrical Units of Measurement" (1889).)
Like all good things, one might also overdo it. As a counterpoint, we have **Goodhart’s Law:** *"When a measure becomes a target, it ceases to be a good measure."*

<!--
Thomson, W. (1891). Popular Lectures and Addresses (Vol. 1, 2nd ed., pp. 80–81). Macmillan and Co.
-->
Many of the measures we have introduced in the prior chapters measure the performance of image system components. When it comes to considering imaging systems, the requirements for astronomy, robotics and consumer photography differ from one another. In this and the following sections we will review multiple measures of image quality that have a different character. These measures are designed specifically for consumer photography applications, and they are measures of whole system performance rather than component performance.

**Goodhart’s Law** as a warning: *"When a measure becomes a target, it ceases to be a good measure."*

The answer depends on your intended use. If the camera is intended to create images that people see, then the design must be guided by the capabilities and limits of the human eye. If the camera serves as input to a robot, or a self-driving car, or a medical image diagnostic system, we expect the camera's design to be evaluated by how well it assists those systems.
In this section we consider specifically spatial resolution requirements for consumer photography systems. The design of these systems is naturally guided by the capabilities and limits of the human eye, which we have been reviewing.

## Digital twins
Engineering progress relies on measurement. Improving a system is an iterative process that involves a loop of designing, measuring, and redesigning. Consequently, performance metrics are fundamental to nearly all engineering disciplines.

*Schade discussion here*

It is also a common principle that systems of even moderate complexity have more than one performance measure. We are often forced to make trade-offs, for example, between a system's speed and its accuracy. We see this in modern AI systems that offer a choice between a 'fast' mode and a more thorough 'thinking' mode.

Imaging systems are no different. They present numerous trade-offs. For instance, increasing a sensor's spatial resolution can reduce the number of photons captured per pixel, thus lowering the signal-to-noise ratio (SNR). Conversely, increasing SNR by using wider color filter bandwidths may reduce color accuracy.
Expand All @@ -41,7 +41,7 @@ The usefulness of the analyses in the transform domain, in engineering generally

I created four Google docs with historical information about CSF measurements, how to download the historical data, and how to imlement the modern models of the historical and more modern data. Integrate those pages here and write some Matlab scripts to create figures.

Show the data he collected of the CSF (1/MTF) he measured that I include in FOV. Maybe in the human spatial encoding chapter.
Show the data he collected of the CSF (1/MTF) he measured that I include in FOV.

The use of harmonics to probe the visual system is quite different from their use in studying typical systems. At many points in this volume I have pointed out that harmonics are particularly valuable stimuli for space-invariant linear systems @sec-appendix-spaceinvariance-overview. These systems have an input and an output. THe use of harmonic stimuli in human vision faces two significant limitations. First, as we have just seen, the system is not at all space-invariant (@fig-cone-mosaic-density). It is justifiable to use harmonics as special stimuli over small regions of the retina, which can be close to space-invariant. Stimuli that span more than a degree or two will not have the special property (harmonics being nearly eigenfunctions) that make them so useful in systems analysis.

Expand Down
Loading