# tikzphysics

Draw mechanics and optics diagrams using ordinary TikZ nodes, paths, and anchors.
The main names are **`block`, `spring`, `pulley`, and `wedge`**. No special command namespace is needed.

**Version 1.2.0 · 2026-09-05**

## Start here

1. Put `tikzphysics.sty` and **all** `tikzlibrarytikzphysics*.code.tex` files beside your document, or install them in your personal TeX tree. Include the new `catalog` file.
2. Load `\usepackage{tikzphysics}`.
3. Compile with pdfLaTeX. The package itself needs neither shell escape nor external programs.

```latex
\documentclass[tikz,border=5mm]{standalone}
\usepackage{tikzphysics}
\begin{document}
\begin{tikzpicture}
  \node[block] (B) at (3,0) {$m$};
  \draw[spring] (0,0) -- node[above] {$k$} (B.west);
\end{tikzpicture}
\end{document}
```

Here `block` chooses an object, `(B)` names it, and `(B.west)` is its left attachment point. `spring` decorates the connection between two coordinates.

## Choose what to learn

| I want to… | Start with… |
| --- | --- |
| Build a spring–block–pulley system | [Complete example below](#spring-block-and-pulley-on-a-wedge) |
| Find every feature and its keys | [Feature reference](docs/reference.md) |
| See keys and anchors while drawing | [Debug explorer](#explore-inside-tikz) |
| Understand dimensions and percentage anchors | [Extended guide](docs/guide.md) |
| Browse rendered diagrams and detailed explanations | [PDF manual](tikzphysics.pdf) |
| Copy a complete document | [Example directory and learning routes](examples/README.md) |

The default block is **1 cm × 1 cm**, and the default pulley diameter is **1 cm**.

## Set your defaults once

```latex
\tikzset{
  every block/.style={minimum width=1cm,minimum height=1cm,fill=white},
  every spring/.style={pre length=3mm,post length=3mm,amplitude=2mm},
  every pulley/.style={minimum size=1cm}
}
```

Then continue using `\node[block]` and `\draw[spring]`. For one exception, put options after the object name:

```latex
\node[block,minimum width=2cm] (B) {$m$};
```

Node and path styles apply built-in settings, `every physics object` or `every physics connection`, and the object-specific hook, in that order. Later local options win. Inside a scope these customisations stay local. `spring/.append style={...}` is also ordinary supported TikZ.

Use explicit units with native `minimum width`, `minimum height`, and `minimum size`. Convenience keys such as `block width=1.2` interpret bare numbers as centimetres. Spring leads accept zero.

## Spring, block and pulley on a wedge

Copy this complete document:

```latex
\documentclass[tikz,border=6mm]{standalone}
\usepackage{tikzphysics}
\tikzset{
  every block/.style={minimum width=1cm,minimum height=1cm,fill=white},
  every pulley/.style={minimum size=1cm,fill=white},
  every spring/.style={pre length=3mm,post length=3mm,
    amplitude=2mm,segment length=2mm}
}
\begin{document}
\begin{tikzpicture}
  \node[wedge,minimum width=6cm,wedge angle=30] (W) {};
  % The contact anchors select the actual incline in every wedge mode.
  \path (W.tangent-before-50) -- (W.tangent-after-50)
    node[midway,sloped,block,anchor=south] (B) {$m_1$};
  \edef\InclineAngle{\geometryvalue{W}{slope angle}}
  \draw[thick] (W.surface-start) -- ++({\InclineAngle+90}:10mm);
  \coordinate (S) at ($(W.surface-start)+({\InclineAngle+90}:5mm)$);
  \draw[spring] (S) -- node[above=3mm,sloped] {$k$} (B.west);
  \node[pulley] (P) at (W.top) {};
  \node[block,minimum width=8mm,anchor=north] (H) at ($(P.east)+(0,-4cm)$) {$m_2$};
  \draw[rope] (B.east) to[over pulley=P] (H.north);
\end{tikzpicture}
\end{document}

```

The hanging block uses a local `minimum width=8mm` override for a slimmer appearance; the default block remains a 1 cm square.

The block height matches the pulley diameter, keeping the incoming string parallel to the incline for this placement. The string follows exact tangent points and the pulley arc. If you change these sizes independently, that alignment is no longer guaranteed.

The older `\physicsstringoverpulley{B.east}{P}{H.north}` command is still supported. Both forms respect scoped `string route` settings.

## Explore inside TikZ

Add `show anchors` or `show keys` to a named object:

```latex
\begin{tikzpicture}
  \node[wedge,show anchors,show keys] (W) {};
\end{tikzpicture}
```

`show keys` displays the feature reference: **defaults, size aliases, named anchors, and percentage families**, not the live values of this particular node. To display a reference without creating an object (including path styles and pics):

```latex
\begin{tikzpicture}
  \physicshelp{spring}
\end{tikzpicture}
```

For a larger object, select the anchors you want to inspect:

```latex
\node[wedge,show anchors,
  physics debug/anchor list={bl,br,top},
  physics debug/anchor families={surface},
  physics debug/anchor samples={0,25,50,75,100}] (W) {};
```

`anchor list=auto` lists every named anchor. Families list their entire `0..100` range in the reference; samples choose points to plot. Native ranges such as `anchor samples={0,1,...,100}` work; `anchor families=all` selects every family. Use `show anchors=false` or `show keys=false` for local overrides. Reference panels and legends can be moved using the debug x/y shift keys described in the manual.

## What can I draw?

| Kind | Features |
| --- | --- |
| Contact surfaces | Platforms, ground, walls, ceilings, wedges, straight and circular ramps |
| Mechanics nodes | Blocks, pulleys, particles, disks, rings |
| Connections and vectors | Springs, ropes, rods, force, velocity, acceleration, torque |
| Named assemblies (`pic`) | Pin supports, roller supports, pendulums |
| Optics | Concave/convex mirrors and lenses, slabs, prisms |

Named assemblies use normal TikZ syntax:

```latex
\pic (A) {pin-support};
\pic (B) at (4,0) {roller-support};
\draw[rod] (A-pivot) -- (B-pivot);
\draw[force] (2,1) -- (2,0);
```

This is a diagram library: forces, trajectories, and optical rays are specified by you. It does not solve dynamics or ray tracing automatically.

## Compatibility and precise attachments

Existing names and numeric shorthand remain available. Prefer explicit anchors such as `(W.surface-50)` and `(L.front-50)`: `(L.30)` is a percentage on optical shapes, while `(P.30)` on a pulley is an angle in degrees.

Use physical anchors for contact with irregular shapes. Their inherited rectangular automatic borders have not been replaced in this release. Standard block and circular-body borders retain normal TikZ behaviour. Use tangent anchors with `sloped` for rotated objects; nonuniform scaling does not preserve circles or perpendicular normals.

## Development

```sh
python3 scripts/generate_reference.py --check
l3build check
l3build doc
```

The manual uses Fourier and `minted`, and therefore needs their dependencies and shell escape when rebuilding. This does not apply to ordinary package use. Run the generator without `--check` after editing feature reference declarations.

Licensed under [LPPL 1.3c or later](LICENSE).