# tikz-chemlab

**Version:** v1.0.0

A TikZ-based reimplementation of the well-known [pst-labo](https://ctan.org/pkg/pst-labo) package for drawing chemical laboratory glassware.

## Overview

tikz-chemlab provides macros for a variety of devices used mainly for chemical applications. Since most of these devices have a standardised design, tikz-chemlab spares you the trouble of having to create them manually. All basic objects are included in the file `tikz-chemlabObj.tex` and are loaded during the start of tikz-chemlab.

This is a TikZ port of pst-labo (v2.07, 2025/07/15) by Denis Girou, Christophe Jorssen, Manuel Luque, and Herbert Voß. The port uses English command names with the `tkz` prefix instead of the original French `pst` names, and all option keys have been translated to English.

## Files

| File | Role |
|------|------|
| `tikz-chemlab.sty` | LaTeX package wrapper (loads TikZ + main file) |
| `tikz-chemlab.tex` | Main implementation (parameter system + high-level macros) |
| `tikz-chemlabObj.tex` | Shape library (low-level drawing primitives) |

Place these three files in the same directory or in the TeX search path.

## Installation

Load the package in the preamble:

```latex
\usepackage{tikz-chemlab}
```

This automatically loads TikZ and the required libraries (`arrows.meta`, `calc`, `patterns`, `shadings`, `decorations.pathmorphing`, `decorations.pathreplacing`).

## Compilation

tikz-chemlab works with any LaTeX engine that supports TikZ:

- **pdflatex** — fully supported (unlike pst-labo, which requires PostScript)
- **xelatex** — fully supported
- **lualatex** — fully supported
- **tectonic** — fully supported

No PostScript dependency. No `latex → dvips → ps2pdf` pipeline needed.

## Quick Start

```latex
\documentclass{standalone}
\usepackage{tikz-chemlab}
\begin{document}
\begin{tikzpicture}[scale=0.5]
  \tkzTestTube
\end{tikzpicture}
\end{document}
```

## Available Macros

| Macro | Description |
|-------|-------------|
| `\tkzTestTube` | Test tube / glass container (tube, roundFlask, beaker, erlenmeyer, reagentBottle, volumetricFlask, watchGlass) |
| `\tkzHeatTube` | Test tube with heating (Bunsen burner, hotplate, bubbling) |
| `\tkzRoundFlask` | Round-bottom flask (with reflux condenser, double tube) |
| `\tkzHeatFlask` | Round-bottom flask with Bunsen burner |
| `\tkzFunnel` | Funnel with test tube |
| `\tkzGraduatedCylinder` | Graduated cylinder (measuring cylinder) |
| `\tkzPipette` | Pipette |
| `\tkzLargePipette` | Large pipette |
| `\tkzTitration` | Titration setup (burette + beaker + optional pH-meter) |
| `\tkzDistillation` | Fractional distillation apparatus |
| `\tkzSeparatoryFunnel` | Separating funnel on support stand |
| `\tkzStand` | Support stand (retort stand) with clamp |
| `\tkzColumn` | Distillation column |

## Key Options

| Option | Default | Description |
|--------|---------|-------------|
| `glassType` | `tube` | Type of glass container |
| `stopper` | `false` | Insert a stopper |
| `clamp` | `false` | Attach a test-tube clamp |
| `tiltAngle` | `0` | Tilt angle in degrees (−65…+65) |
| `liquidLevel1/2/3` | `50/0/0` | Liquid levels (0–100, percentage) |
| `liquidStyle1/2/3` | `liquidStyle1/2/3` | Liquid styles |
| `substance` | `(empty)` | Substance macro |
| `solid` | `(empty)` | Solid substance macro |
| `burette` | `true` | Show/hide burette |
| `pHMeter` | `false` | Show pH-meter |
| `magneticStirrer` | `true` | Show magnetic stirrer / hotplate |
| `bunsenBurner` | `true` | Show Bunsen burner |
| `bubbling` | `false` | Add bubbling test tube |
| `gasCollection` | `false` | Add gas-collection vessel |
| `label` | `false` | Display label |
| `Number` | `(empty)` | Label text |
| `buretteLevel` | `20` | Burette liquid level |
| `buretteColor` | `VeryPaleOrange` | Burette liquid colour |
| `TapOpen` | `false` | Separating funnel tap open/closed |

## Line Width Styles

Six predefined styles available via `\chemlabset{style=...}`:

| Style | Outline | Ellipse | Tube ellipse | Graduation |
|-------|---------|---------|--------------|------------|
| `default` | 0.053 cm | 0.07 cm | 0.08 cm | 0.02 cm |
| `publication` | 0.4 pt | 0.6 pt | 0.8 pt | 0.4 pt |
| `presentation` | 0.8 pt | 1.2 pt | 1.6 pt | 0.6 pt |
| `schematic` | 0.6 pt | 0.8 pt | 1.2 pt | 0.4 pt |
| `draft` | 0.4 pt | 0.4 pt | 0.4 pt | 0.4 pt |
| `bold` | 1.2 pt | 1.6 pt | 1.6 pt | 0.8 pt |

Line widths automatically scale with the TikZ `scale` factor.

## Migration from pst-labo

| pst-labo | tikz-chemlab |
|----------|--------------|
| `\pstTubeEssais` | `\tkzTestTube` |
| `\pstDosage` | `\tkzTitration` |
| `\pstEprouvette` | `\tkzGraduatedCylinder` |
| `\pstBallon` | `\tkzRoundFlask` |
| `\pstEntonnoir` | `\tkzFunnel` |
| `\pstSeparateFunnel` | `\tkzSeparatoryFunnel` |
| `\pstChauffageTube` | `\tkzHeatTube` |
| `\pstChauffageBallon` | `\tkzHeatFlask` |
| `\pstDistillation` | `\tkzDistillation` |
| `\pstpipette` | `\tkzPipette` |
| `\pstSupport` | `\tkzStand` |
| `\pscolon` | `\tkzColumn` |

Key mappings: `tubePenche` → `tiltAngle`, `niveauLiquide1` → `liquidLevel1`, `bouchon` → `stopper`, `becBunsen` → `bunsenBurner`, `etiquette` → `label`, etc.

See the full documentation for complete mapping tables.

## Documentation

- `tikz-chemlab-doc.tex` / `tikz-chemlab-doc.pdf` — English documentation
- `tikz-chemlab-zh-doc.tex` / `tikz-chemlab-zh-doc.pdf` — Chinese documentation (中文使用手册)

## Credits

Original pst-labo authors:

- Denis Girou
- Christophe Jorssen
- Manuel Luque
- Herbert Voß

tikz-chemlab is a TikZ port that preserves the original visual appearance and default values as closely as possible. All shape coordinates were derived from the original `pst-laboObj.tex`.

## License

This work is distributed under the LaTeX Project Public License v1.3c.