# Extended guide

`tikzphysics` is a TikZ-native library for drawing classical-physics diagrams in
LaTeX. It adds reusable shapes, styles, keys, and geometric anchors while
keeping the normal TikZ workflow: diagrams are still built with `\node`,
`\draw`, `\path`, and `\tikzset`.

Version: **1.2.0 (2026-09-05)**

Start with the [quick start](../README.md). The [feature reference](reference.md) lists keys and anchors; the [manual](../tikzphysics.pdf) includes rendered examples and the new debug explorer.

## Included modules

- `tikzphysics.surface`: single-polygon, sharply mitered bent platforms; wedges, ground, ceilings,
  and walls.
- `tikzphysics.ramps`: continuous wall--floor--incline ramps and filled circular
  ramps, with surface, tangent, and normal anchors.
- `tikzphysics.mechanics`: configurable blocks, a spring path style, and pulleys, plus strings that
  compute exact pulley tangencies and circular contact arcs.
- `tikzphysics.optics`: concave and convex mirrors, biconvex and biconcave lenses, slabs,
  and prisms with named and parametric optical-surface anchors.
- `tikzphysics.core`: unit-aware dimensions, parametric anchors, and debug tools.

Object-specific controls use concise names where they read naturally, for
example `wedge height`, `mirror radius`, `strip width`, and `prism apex angle`.
Longer collision-safe forms begin with `physics`, such as
`physics mirror radius` and `physics strip width`.
Ordinary node sizing uses the familiar TikZ keys `minimum width`,
`minimum height`, and `minimum size`; concise unit-aware convenience keys and
their collision-safe `physics ...` aliases remain available when useful.

The primary node styles are intentionally concise:

| Short style | Collision-safe style | Object |
| --- | --- | --- |
| `platform` | `physicsplatform-both` | Platform with independently configurable left and right walls |
| `platform-left`, `platform-right`, `platform-both` | `physicsplatform-left`, `physicsplatform-right`, `physicsplatform-both` | Explicit bent-platform variants |
| `platform-left-up`, `platform-right-up` | `physicsplatform-left-up`, `physicsplatform-right-up` | One-wall presets using `wall angle=90` |
| `wedge` | `physicswedge` | Inclined plane |
| `ramp`, `ramp-left` | `physicsramp` | Continuous wall--floor--linear-incline body |
| `curved-ramp`, `curved-ramp-left` | `physicscurvedramp` | Circular contact ramp with a filled body |
| `ground`, `ceiling` | `physicsground`, `physicsceiling` | Horizontal contact strips |
| `wall-left`, `wall-right` | `physicswall-left`, `physicswall-right` | Vertical contact strips |
| `block`, `pulley` | `physicsblock`, `physicspulley` | Mechanics nodes |
| `spring` | `physics spring`, `physicsspring` | Coil decoration used with `\draw` |
| `concave-mirror`, `convex-mirror` | `physicsconcavemirror`, `physicsconvexmirror` | Curved reflecting surfaces |
| `convex-lens` | `physicsconvexlens` | Symmetric biconvex lens |
| `concave-lens` | `physicsconcavelens` | Symmetric biconcave lens |
| `slab` | `physicsslab` | Unfilled parallel-sided rectangular slab |
| `prism` | `physicsprism` | Unfilled isosceles triangular prism |

TikZ style names are global. If another package or the surrounding document
already defines a generic name such as `block`, use the corresponding
`physics...` form.

Bent-wall directions are continuous. The only excluded directions are a left
wall at 0 degrees and a right wall at 180 degrees (modulo 360), because those
fold directly back over the floor and have no finite miter.

## Requirements

- LaTeX2e
- PGF/TikZ, including the standard `calc`, `patterns`, `angles`, and
  `decorations.pathmorphing` libraries

No shell escape, external program, special font, or platform-specific runtime
is required when using the package.

## Installation

After publication, install `tikzphysics` through TeX Live or MiKTeX. For a manual
installation, copy these files into a directory searched by TeX:

- `tikzphysics.sty`
- `tikzlibrarytikzphysics.code.tex`
- `tikzlibrarytikzphysics.core.code.tex`
- `tikzlibrarytikzphysics.catalog.code.tex`
- `tikzlibrarytikzphysics.surface.code.tex`
- `tikzlibrarytikzphysics.ramps.code.tex`
- `tikzlibrarytikzphysics.mechanics.code.tex`
- `tikzlibrarytikzphysics.optics.code.tex`

For a private TeX tree, a suitable location is
`tex/latex/tikzphysics/`; refresh the filename database afterward if your TeX
distribution requires it.

## Quick start

Load all modules:

```latex
\usepackage{tikzphysics}
```

Or load only the modules needed by a document:

```latex
\usepackage{tikz}
\usetikzlibrary{tikzphysics.ramps, tikzphysics.mechanics}
```

The following is a complete document. Copy it into a new Overleaf project with
the package installed or with the standalone `tikzphysics.sty` bundle beside
the main file:

```latex
\documentclass[tikz, border=6mm]{standalone}
\usepackage{tikzphysics}

\begin{document}
\begin{tikzpicture}
  \node[platform, minimum width=5cm, minimum height=2cm]
    (platform) at (0,0) {};

  \node[pulley, minimum size=8mm]
    (pulley) at (platform.north east) {};
\end{tikzpicture}
\end{document}
```

Native and convenience sizing can be used side by side:

| Shape/property | Native TikZ (preferred) | Package convenience |
| --- | --- | --- |
| Block width/height | `minimum width`, `minimum height` | `block width`, `block height` |
| Pulley diameter | `minimum size` | `pulley diameter` |
| Platform width/depth | `minimum width`, `minimum height` | `platform width`, `platform depth` |
| Ground or ceiling width/depth | `minimum width`, `minimum height` | `ground ...`, `ceiling ...` |
| Wall thickness/height | `minimum width`, `minimum height` | `wall thickness`, `wall height` |
| Wedge width | `minimum width` | `wedge width` |
| Straight-ramp width | `minimum width` | — |
| Slab width/height | `minimum width`, `minimum height` | `slab width`, `slab height` |
| Prism width/height | `minimum width`, `minimum height` | `prism width`, `prism height` |

Put the shape style first and the sizing keys after it. If both forms are
present, the last value wins. `wedge height` is deliberately not
replaced by `minimum height`: it selects the wedge's geometry when no angle is
given.

The wedge keys also have collision-safe forms:

| Concise key | Collision-safe alias |
| --- | --- |
| `wedge width` | `physics wedge width` |
| `wedge height` | `physics wedge height` |
| `wedge angle` | `physics wedge angle` |
| `wedge right angle at` | `physics wedge right angle at` |

### Named wedge geometry values

A named wedge records its resolved geometry. Read a value with
`\geometryvalue{node}{property}`; the collision-safe command is
`\tikzphysicsgeometryvalue`. The result belongs to that particular node, so
several wedges can be queried independently:

```latex
\node[wedge, minimum width=6cm, wedge angle=30] (W) at (0,0) {};
\node[block, minimum width=1cm, minimum height=1cm,
      rotate=\geometryvalue{W}{slope angle}, anchor=south]
  at (W.slope-mid) {$m$};

\node at (W.bl) {$\geometryvalue{W}{left angle}^\circ$};
```

Interior-angle properties are `left angle`, `right angle`, and `top angle`, at
anchors `bl`, `br`, and `top`. Local edge-direction properties are
`base direction`, `left edge direction`, and `right edge direction`.
`slope angle` (also `slope direction` or `surface angle`) is the rotation of
the contact surface selected by `slope-mid`, so it is the value to use for a
block placed there. It is negative for a wedge that descends left-to-right.
For `wedge right angle at=top`, `slope-mid` selects the left face and
`right slope angle` belongs to `slope-right-mid`. Directions are in degrees
counter-clockwise from local positive x, without a degree symbol. The
remaining values are `base angle`, `right edge angle`, `width`, `height`, and
`right angle at`.

The node must be named and completed before it is queried. Directions describe
the wedge before a node-specific transformation. They work directly when the
wedge and attached object share the same transformed scope. For independently
rotated or non-uniformly scaled nodes, use the edge anchors and TikZ's `sloped`
placement so the final rendered geometry determines the orientation. See
`examples/wedge-geometry-values.tex` for a complete annotated document.

The remaining concise controls follow the same rule:

| Concise key | Collision-safe alias |
| --- | --- |
| `platform width`, `platform depth`, `strip width` | `physics platform width`, `physics platform depth`, `physics strip width` |
| `wall angle`, `left wall angle`, `right wall angle` | The same keys prefixed with `physics` |
| `block width`, `block height` | `physics block width`, `physics block height` |
| `pulley diameter`, `pulley axle radius`, `pulley axle color` | The same keys prefixed with `physics` |
| `string start solution`, `string end solution`, `string route`, `string wrap` | The same keys prefixed with `physics` |
| `ground width/depth`, `ceiling width/depth`, `wall thickness/height` | The same keys prefixed with `physics` |
| `ramp direction/run/rise/angle/depth`, `ramp wall height/width`, `ramp guide length` | The same keys prefixed with `physics` |
| `curved ramp radius/angle/floor length/back extension` | The same keys prefixed with `physics` |
| `mirror radius/thickness/aperture angle` | The same keys prefixed with `physics` |
| `convex lens radius/thickness/aperture angle` | The same keys prefixed with `physics` |
| `concave lens radius/thickness/aperture angle` | The same keys prefixed with `physics` |
| `slab width/height`, `prism width/height/apex angle` | The same keys prefixed with `physics` |

Shape-specific controls such as wall angle, strip width, axle styling, and
optical geometry use the names documented for their shapes; collision-safe
`physics ...` aliases are available where listed.

Platform directions use `wall angle`, `left wall angle`, and `right wall angle`.
Their collision-safe aliases add the `physics` prefix. Wedges use the `dots`
material pattern by default; a later `pattern=...` option overrides it.

## Spring paths

`spring` is used directly on a path. Its two endpoints determine the complete
length and direction:

```latex
\draw[spring,
      pre length=5pt, post length=5pt,
      amplitude=4.5pt, segment length=4.5pt,
      aspect=0.5]
  (A) -- node[above] {$k$} (B);
```

The spring is not a node and therefore has no private anchors. Use the path
endpoints and ordinary TikZ nodes along the path. Its keys are `pre length`,
`post length`, `amplitude`, `segment length`, and `aspect`; collision-safe
aliases begin with `physics spring ...`.

## Percentage anchors

Percentage anchors place something partway along a named edge or curved
surface without coordinate arithmetic. Their explicit form is:

```latex
(node-name.family-number)
```

The number is an integer from `0` to `100`; do not include a `%` sign. `0` is
the family's documented start, `50` is halfway along it, and `100` is its end.
For example:

```latex
\node[wedge, wedge width=6cm, wedge angle=30] (W) at (0,0) {};
\node[block, rotate=30, anchor=south] at (W.slope-50) {$m$};
\fill[red] (W.slope-25) circle (1.5pt);
```

Here `W` is the node name, `slope` chooses one edge, and `25` means 25 percent
from `slope-0` towards `slope-100`. Wedge slope direction runs from the top
vertex to the lower foot, so `slope-25` is near the top.

Common directions are:

| Family | Direction from `0` to `100` |
| --- | --- |
| Platform `floor-top-T` | Right floor corner to left floor corner |
| Platform `wall-outer-T` | Platform corner to far wall end |
| Wedge `base-T` | `bl` to `br` |
| Wedge `right-T` | `br` to `top` |
| Wedge `slope-T` | `top` to `bl` |
| Ramp `surface-T` | `surface-start` to `surface-end` along the complete contact path |
| Curved ramp `curve-T` | Start to end of the circular portion only |
| Mirror/lens/slab surfaces | Bottom to top |
| Prism `base-T` | `base-left` to `base-right` |
| Prism `left-T` | `apex` to `base-left` |
| Prism `right-T` | `base-right` to `apex` |

On a multi-part ramp, `surface-50` means halfway by distance along the entire
contact path; it is not necessarily the visual centre or the floor-to-ramp
joint. On circular families, the percentage follows the arc.

Ramps and optical shapes also provide `(name.T)` shorthand. For ramps it means
`surface-T`; for mirrors it means `surface-T`; for lenses and slabs it means
`front-T`; and for prisms it means `left-T`. Prefer the explicit family form
while learning, especially because ordinary TikZ numeric anchors can instead
mean an angle around a node. Platforms and wedges require explicit forms such
as `(P.floor-top-50)` and `(W.slope-50)`.

See `examples/percentage-anchors-beginner.tex` for an annotated copy-paste
document and `examples/surface-numeric-anchors.tex` for a larger edge gallery.

## Combining coordinates for horizontal connections

TikZ's native projection syntax can take x from one anchor and y from another:

| Syntax | Result |
| --- | --- |
| `(A |- B)` | x from `A`, y from `B` |
| `(A -| B)` | x from `B`, y from `A` |

For a horizontal spring from a ramp's vertical wall to a block, use:

```latex
\coordinate (A) at (R.wall-mid |- B.west);
\draw[spring] (A) -- (B.west);
```

This requires no measured offset: both endpoints necessarily use the y-value
of `B.west`. For `platform-left-up`, replace `R.wall-mid` with
`P.wall-outer-mid`. For a right upward wall, project from its wall anchor to
`B.east`. This is exact for vertical walls; an arbitrary angled-wall
intersection requires TikZ's `intersections` library. The complete examples
are in `examples/coordinate-projection.tex` and
`examples/ramp-straight-system.tex`.

## Rare ramp geometries

The ramp objects are true node shapes and each body is one closed path. The
straight `ramp` has a vertical wall, a horizontal floor, and a linear incline
with a sharp floor-to-incline corner. `minimum width` controls its overall
horizontal width; `ramp run`, `ramp angle` or `ramp rise`, `ramp wall height`,
`ramp wall width`, and `ramp depth` control the remaining geometry.
After naming the node, `\physicsrampangle{R}{$30^\circ$}` draws the dashed
reference ray, acute angle arc, and label at that sharp corner.

The `curved-ramp` contact surface begins with a horizontal floor and joins its
circular arc with the same horizontal tangent. Its default floor extends 2.5cm
left of the arc foot; set `curved ramp floor length` to change it. A 90-degree
sweep ends with a vertical tangent. Use `curved ramp radius`, `curved ramp angle`, and
`curved ramp back extension`. Both shapes accept `ramp direction=left` or
`right`; the left-facing convenience styles are `ramp-left` and
`curved-ramp-left`.

Both ramps provide `surface-0` through `surface-100` and the shorthand `.0`
through `.100` over the complete contact surface. Curved ramps additionally
provide `curve-0..100`, `curve-tangent-before/after-T`, and `curve-normal-T`
for the circular portion alone. This places a block on the arc at its exact tangent:

```latex
\node[curved-ramp, curved ramp radius=4cm] (R) at (0,0) {};
\path (R.curve-tangent-before-60) -- (R.curve-tangent-after-60)
  node[midway,sloped,block,anchor=south] (B) {$m$};
\draw[->] (B.north) --
  ($(B.north)+(R.curve-normal-60)-(R.curve-60)$) node[above left] {$N$};
```

The last coordinate expression translates the exact normal vector to start at
the top of the block, keeping the force arrow out of the block body.

For a block-pulley system, use
`\physicsstringoverpulley{B.east}{P}{H.north}`. It computes both tangent contact
points and the circular wrap around pulley node `P`; the string does not rely
on approximate compass anchors. The default `string route=surface-right`
is intended for a block on a horizontal or rising surface with the mass
hanging on the pulley's right. The approaching string remains parallel to the
surface and passes over the upper pulley rim. The optional argument also
accepts `over`, `under`, and `shortest`, or the individual tangent-solution and
wrap keys.

For a wedge-mounted pulley, place its centre directly at the wedge vertex. If
the string starts at `B.east`, the default `1cm` pulley diameter and a `1cm`
block height keep that tangent exactly parallel to the incline:

```latex
\node[block, block height=1cm, rotate=30, anchor=south]
  (B) at (W.slope-mid) {$m$};
\node[pulley] (P) at (W.top) {};
```

A complete optics composition:

```latex
\begin{tikzpicture}
  \node[convex-lens, convex lens radius=3cm,
        convex lens thickness=0.2cm,
        convex lens aperture angle=25] (L) at (0,0) {};
  % Snell-law values for n(lens)/n(air)=1.50 and this fixed geometry.
  \coordinate (Lexit) at ($(L.center)+(0.29194,0.72588)$);
  \coordinate (Lf) at ($(L.center)+(2.93841,0)$);
  \node[slab, minimum width=1.2cm, minimum height=3cm]
    (S) at (5,0) {};
  \node[prism, prism width=3cm, prism apex angle=60]
    (P) at (10,0) {};

  \draw[red,->] ($(L.80)+(-3,0)$) -- (L.80) -- (Lexit) -- (Lf);
  \draw[red,->] (3.2,-0.8) -- (S.30) -- (S.back-65) -- (7,0.8);
  \draw[red,->] (8,-0.4) -- (P.50) -- (P.right-65) -- (12,0.8);
\end{tikzpicture}
```

The non-axial lens ray changes direction at both interfaces. The package
provides the geometry and anchors but does not automatically solve Snell's
law; if the lens keys or refractive indices change, recompute the exit and
focal coordinates.

For `prism`, an explicitly supplied `prism apex angle` derives the height and
takes precedence over `minimum height` or `prism height`.

Optical shorthand percentage anchors are summarized in the percentage-anchor
section above. For example, `(L.50)` is the middle of a lens's front surface
and `(L.80)` is near its upper edge.

Bare dimension values are interpreted as centimetres; explicit TeX units such
as `8mm`, `12pt`, and `1in` are preserved by package convenience keys. Native
TikZ sizing keys should be given explicit units.

## Documentation and examples

The complete user manual is `tikzphysics.pdf`, built from `tikzphysics.tex`.
Standalone source examples are provided in `examples/`, including complete
bent-platform configuration and key-variant galleries. Start with
`examples/short-names-platform-pulley.tex` for the smallest complete document.
Use `examples/short-names-wedge-variants.tex` for complete angle-, height-,
width-, and right-angle-mode examples.
Use `examples/optics-components.tex` for the complete optics gallery and
`examples/optics-ray-composition.tex` for named and numeric surface anchors in
ray paths. `examples/optics-complete-ray-diagrams.tex` contains complete
converging and diverging diagrams for both lenses and mirrors.
Start with `examples/percentage-anchors-beginner.tex` when learning percentage
anchors; it labels the direction and shows both explicit and short forms.
The ramp examples are `ramp-straight-system.tex`, `ramp-curved-system.tex`,
and `ramps-gallery.tex`.
The pulley examples include horizontal-plane, inclined-plane, bent-platform,
two-hanging-mass, and six string-routing arrangements. A terminal quick reference is available
through:

```sh
./tikzphysics-help
./tikzphysics-help platform
```

## Development

The package uses `l3build` for regression testing and release packaging:

```sh
l3build check
l3build doc
l3build ctan
```

The regression suite checks fixed platform corners, wall extents, straight and
circular ramp endpoints, tangent/normal guides, mirror and lens arc endpoints, shorthand optical anchors,
slab and prism surface
endpoints, and unit-aware sizing.

## License

Copyright (C) 2026 Vaibhav Blayer.

This material is subject to the LaTeX Project Public License version 1.3c or
later. The work has LPPL maintenance status `maintained`; the Current
Maintainer is Vaibhav Blayer. See `LICENSE` for details.