# Optics percentage anchors

Use integer percentages from 0 through 100, for example `(L.surface-25)`.
Arc percentages interpolate the arc angle (and hence arc length), not height.
Straight edges interpolate distance. All directions are local to the node;
rotation and scaling transform the attachment points with the object.

| Shape | Family | Direction from 0 to 100 |
|---|---|---|
| Both mirrors | surface, front, back | Bottom to top; surface is the reflecting face |
| Both lenses | surface, front, back | Bottom to top; surface equals front |
| Slab | surface, front, back | Bottom to top; surface equals front |
| Mirrors, lenses, slab | top | Right to left |
| Mirrors, lenses, slab | bottom | Left to right |
| Prism | base | Base-left to base-right |
| Prism | left, entry, surface | Apex to base-left |
| Prism | right, exit | Base-right to apex |

Prism entry and exit are geometric aliases, not automatic ray tracing.
Existing prism directions are preserved. Bare `.0` through `.100` still
select the primary surface on every optical shape. Prefer explicit families
to distinguish percentage positions from TikZ's numeric angle anchors.

Mirror and lens caps span their finite edge thickness. Named anchors such as `top`, `bottom`, and `front-mid` remain
available and coincide with the corresponding 50-percent point.

```tex
\node[convex-lens] (L) {};
\draw[->] (-3,0) -- (L.surface-50);
\draw (L.top-25) -- ++(0,0.5);
\node[prism] (P) at (5,0) {};
\draw[->] (P.entry-35) -- (P.exit-65);
```

Use `show anchors` with `physics debug/anchor families={surface,top,bottom}`
and `physics debug/anchor samples={0,25,50,75,100}` to inspect selected
families. The generated reference cards also list every available family.
See `examples/optics-percentage-anchors.tex` for all six shapes.

## Plane mirrors and asymmetric lenses

| Style | Default faces | Default front/back radii |
|---|---|---|
| `plane-mirror` (also `plane mirror`) | Both flat; front is reflecting | Not used |
| `plano-convex-lens` (also `plano-convex`) | Flat front, convex back | Unused / 5 cm |
| `plano-concave-lens` (also `plano-concave`) | Flat front, concave back | Unused / 5 cm |
| `positive-meniscus-lens` | Convex front, concave back; thicker centre | 4 cm / 6 cm |
| `negative-meniscus-lens` | Convex front, concave back; thicker rim | 6 cm / 4 cm |

All five provide `surface`, `front`, and `back` percentages from bottom to
top; `surface` and bare numeric anchors select the front face. `top` runs
right to left and `bottom` left to right. Flat faces interpolate height;
circular faces interpolate angle. Named `front-mid`, `back-mid`,
`front-top`, `front-bottom`, `back-top`, `back-bottom`, `surface-mid`,
`surface-top`, `surface-bottom`, `vertex`, `top`, and `bottom` are available.
The node centre is halfway between the on-axis face vertices.

Plane mirrors accept `mirror height` (default 3 cm) and `mirror thickness`
(default 0.25 cm). The other new variants accept `lens height` (3 cm),
`lens thickness` (0.2 cm), `lens front radius`, and `lens back radius`.
`lens radius` sets both radii. These new lens keys apply to the asymmetric
variants; existing biconvex/biconcave shapes keep their existing keys.
Bare length numbers are centimetres. Height and thickness must be positive;
each curved face radius must exceed half the height. Flat faces ignore
radius. Thickness means the **minimum material thickness**, whether at the
centre or the rim, preventing crossing faces.

Meniscus names identify the default geometry. Changing radii can change
which region is thicker; these nodes do not calculate focal length or rays.
Use `xscale=-1` to reverse any variant and `rotate` to orient it. Anchors
remain attached to their original faces after transformation.
`biconvex-lens` and `biconcave-lens` are aliases of the existing lens styles.

```tex
\node[plane-mirror,mirror height=4,mirror thickness=.15] (M) {};
\node[plano-concave-lens,lens height=3,lens radius=5,
      lens thickness=.25,xscale=-1] (L) at (4,0) {};
\draw[->] (L.surface-50) -- (M.surface-50);
```

Each canonical style has a collision-safe `physics...` form, for example
`physicsplanemirror` and `physicsplanoconcavelens`, and its own
`every <style>` hook. `show anchors`, `show keys`, and `\physicshelp`
use the same reference-card machinery as the existing optics shapes.
The visual gallery is `examples/optics-variants.tex`.

## Choosing dimensions

For existing symmetric lenses, use `convex lens radius`, `convex lens
thickness`, and `convex lens aperture angle`, or the corresponding
`concave lens ...` keys. Convex thickness is the rim thickness; concave
thickness is the centre thickness. Their aperture angle sets half the
angular opening, and height follows from radius and angle.

For new asymmetric lenses, height is specified directly. With half-height
h and radius R, the face sag is R - sqrt(R*R - h*h). The minimum-thickness
setting adds enough space between the two faces that they remain separate
at both the axis and the rim. Front and back radii may be set independently.
A plano-convex lens is thicker on-axis; a plano-concave lens is thicker at
the rim. Setting the two meniscus radii equal gives constant horizontal
thickness. Use moderate dimensions or ordinary TikZ scaling for very large
objects, as PGF geometry uses fixed-point arithmetic.

`minimum width` and `minimum height` are not sizing keys for the new
variants: use the documented lens/mirror keys. Compass anchors describe
extents; explicit face families locate the physical boundary. Automatic
border intersection remains an approximation and should not be used to
place an optical contact accurately.

## Styling, orientation, and debugging

All optics styles default to black-and-white rendering: black outlines,
white or unfilled interiors, and black hatching where applicable. The new
galleries use black markers. Color is opt-in through ordinary TikZ `draw`,
`fill`, and `pattern color` keys in the user's document; no global color
setting is imposed by these variants.

```tex
\begin{tikzpicture}
  \node[plano-convex-lens,lens height=2.5,lens radius=4,
        rotate=15] (L) {};
  \node[negative-meniscus-lens,xscale=-1,
        lens height=2.5,lens front radius=6,lens back radius=4] (N) at (4,0) {};
  \draw[->] (L.back-65) -- (N.front-65);
\end{tikzpicture}
```

This connects chosen boundary points; it is a composition example, not a
calculated refracted ray. Curved-face percentages refer to arc length, so
identical percentages on unequal radii do not generally have identical
heights except at the endpoints and midpoint.

```tex
\node[plano-concave-lens,show anchors,show keys,
      physics debug/anchor families={surface,back,top,bottom},
      physics debug/anchor samples={0,25,50,75,100}] (L) {};
```

Reference cards can be large. Inspect one object at a time or request fewer
families and samples. `\physicshelp{plano-concave-lens}` gives the compact
feature reference without adding a lens. The new shapes also support
`every physics object` and individual `every plane-mirror`,
`every plano-convex-lens`, `every plano-concave-lens`,
`every positive-meniscus-lens`, and `every negative-meniscus-lens` hooks.

## Single-file Overleaf installation

1. Upload `output/overleaf/tikzphysics.sty` into the same project directory
   as the main document, replacing the previous local copy.
2. Keep `\usepackage{tikzphysics}` in the preamble. No sibling
   `tikzlibrarytikzphysics.*.code.tex` files are required.
3. Compile `optics-variants.tex` to check the five new styles, or use the
   updated `main.tex` starter. A complete upload ZIP is provided alongside
   the single file.

A project-local package takes precedence over Overleaf's installed version.
The generated file includes the reference catalogue, debug helpers, and all
modules. Regenerate it after source changes with
`python3 scripts/generate_reference.py` followed by
`python3 scripts/build_overleaf_bundle.py`. Both accept `--check` to detect
stale generated files. The direct-upload runtime does not by itself update the
published CTAN or TeX Live package.

## Compatibility and troubleshooting

- Existing curved mirrors, symmetric lenses, slab and prism styles retain
  their dimensions and anchors. The new families are additive.
- `(L.30)` is a percentage, not a 30-degree border anchor. Prefer
  `(L.surface-30)` to make this explicit.
- A radius error means the curved face cannot span the requested height.
  Increase that radius or reduce `lens height`.
- To change a plano lens's curvature, set `lens back radius` or `lens radius`;
  its flat front ignores `lens front radius`.
- Reflections transform geometry; they do not change anchor names.
- If a style is unknown on Overleaf, verify that the newly generated local
  `tikzphysics.sty` was uploaded beside the selected main document.