Figure Guide for PhysicsLibrary
2026-08-30 18:43:30
2026-08-30 20:19:23
updated about latex2html is now legacy but we need to redo a lot of this article now with that in mind.
% Suggested title:
% Creating PhysicsLibrary figures with TikZ
%
% PhysicsLibrary site-documentation source.
% This guide is intended for the PhysicsLibrary documentation center.
\documentclass{article}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{geometry}
\usepackage{graphicx}
\geometry{a4paper, margin=1in}
\title{Figure Guide for PhysicsLibrary}
\author{}
\date{}
\begin{document}
\maketitle
\section{Purpose}
TikZ is the preferred source format for many PhysicsLibrary diagrams because it produces figures whose geometry, labels, arrows, colors, and mathematical notation can be edited reproducibly. It is particularly well suited to coordinate-frame diagrams, free-body diagrams, vector geometry, rotation sequences, signal-flow diagrams, block diagrams, and other technical illustrations in which the meaning of every line and label matters.
The recommended primary editor for PhysicsLibrary TikZ work is
\PMlinkexternal{the TikZ online editor}{https://tikz.dev/editor/}.
The editor is part of the online PGF/TikZ documentation site and provides a convenient place to write, inspect, and refine TikZ source while working in a browser. The main PGF/TikZ documentation is available at
\PMlinkexternal{tikz.dev}{https://tikz.dev/}.
\section{Important current renderer limitation}
\textbf{Raw TikZ source should not presently be placed in a PhysicsLibrary article with the expectation that the HTML renderer will draw it.}
PhysicsLibrary still uses an older l2h/LaTeX2HTML rendering path for part of the site. At present, raw \texttt{tikzpicture} environments are not a dependable inline rendering method in that pipeline. Direct TikZ rendering may become a future PhysicsLibrary feature, but articles should currently use a rendered PNG image for the visible figure.
The recommended policy is therefore:
\begin{enumerate}
\item create the figure in TikZ;
\item keep the TikZ source as the editable master;
\item render or export the finished figure as a PNG;
\item upload the PNG to the PhysicsLibrary article;
\item upload the corresponding TikZ \texttt{.tex} source in the article's file box as a companion source file; and
\item include only the PNG in the article body.
\end{enumerate}
This preserves immediate renderer compatibility while also preserving the exact source needed to revise the figure later.
\section{Recommended workflow}
\subsection{Step 1: define the physical content before drawing}
A technical figure should first answer a physics question, not a graphics question. Before editing TikZ, write down what the diagram must communicate. Examples include:
\begin{itemize}
\item which frame is the reference frame and which frame is moving;
\item whether the transformation is active or passive;
\item whether a rotation axis is fixed or belongs to an intermediate moving frame;
\item the positive rotation sense;
\item which vectors or axes are unchanged by the operation;
\item whether the drawing is geometrically exact or intentionally schematic; and
\item which labels must correspond directly to equations in the article.
\end{itemize}
This step is especially important for Euler-angle, quaternion, rigid-body, and coordinate-transformation figures. A visually attractive diagram with the wrong rotation sense is worse than no diagram.
\subsection{Step 2: create the TikZ source in the main editor}
Open
\PMlinkexternal{https://tikz.dev/editor/}{https://tikz.dev/editor/} or edit on the web \PMlinkexternal{https://tikz.dev/editor/web/}{https://tikz.dev/editor/web/}
and create the figure as a small standalone TikZ document. A useful starting template is:
\begin{verbatim}
\documentclass[tikz,border=8pt]{standalone}
\usepackage{amsmath,amssymb}
\usetikzlibrary{arrows.meta,calc,positioning}
\begin{document}
\begin{tikzpicture}[
>=Latex,
line cap=round,
line join=round
]
% Figure content here.
\end{tikzpicture}
\end{document}
\end{verbatim}
The \texttt{standalone} class is convenient because the compiled output is tightly cropped around the figure. The \texttt{arrows.meta}, \texttt{calc}, and \texttt{positioning} libraries cover many common PhysicsLibrary diagrams without requiring an unnecessarily complicated preamble.
\subsection{Step 3: use LaTeX notation inside the figure}
Labels should normally be written as LaTeX mathematics rather than baked into an external drawing program. For example:
\begin{verbatim}
\node at (2,1) {$x_A$};
\node at (3,2) {$+\theta$ about $y_1$};
\end{verbatim}
This keeps mathematical notation consistent with the surrounding article and makes later symbol changes straightforward.
For a PhysicsLibrary article that uses frame notation such as
\begin{equation}
{}^B\mathbf v = {}^B C_A\,{}^A\mathbf v,
\end{equation}
use the same superscripts, subscripts, axis names, angle symbols, and sign conventions in the figure.
\subsection{Step 4: refine the geometry and labeling}
A good technical diagram should remain readable at article width. In particular:
\begin{itemize}
\item use one clearly identifiable origin for coordinate axes that share an origin;
\item keep arrowheads away from text labels;
\item do not let flow arrows pass through boxes;
\item leave visible whitespace between titles, panel headings, arrows, and annotations;
\item keep axis labels near the corresponding arrowheads;
\item use line weights heavy enough to survive PNG conversion;
\item prefer a white background for normal PhysicsLibrary figures; and
\item avoid decorative elements that do not communicate physics.
\end{itemize}
For multi-panel figures, keep panel geometry and typography consistent. If the same axis survives from one intermediate frame to the next, draw it in the same direction and location whenever the viewpoint allows it.
\subsection{Step 5: check the physics}
Before exporting the figure, perform a convention check. For rotation figures, useful checks include:
\begin{itemize}
\item verify the right-hand rule;
\item verify the direction from the original axis to the rotated axis;
\item verify which axis is fixed by the rotation;
\item verify active versus passive interpretation;
\item verify the map direction used in the article;
\item verify intrinsic versus extrinsic axis selection;
\item verify that intermediate-frame labels are carried consistently between panels; and
\item compare the picture against a simple $90^\circ$ diagnostic case whenever possible.
\end{itemize}
For example, under the common PhysicsLibrary passive rotation convention
\begin{equation}
{}^B\mathbf v = {}^B C_A\,{}^A\mathbf v,
\end{equation}
a positive physical frame rotation still follows the positive right-hand rule. The opposite sign appears in the numerical coordinate map, not in the physical frame-rotation arrow. This distinction should be checked explicitly when constructing axis-rotation figures.
\subsection{Step 6: export or render a PNG}
The finished TikZ source is the master version, but the PhysicsLibrary article should currently display a PNG. Use the browser editor's available export workflow when suitable, or compile the same TikZ source in another LaTeX environment and convert the resulting PDF to PNG.
A useful command-line workflow is:
\begin{verbatim}
pdflatex figure.tex
pdftocairo -png -singlefile figure.pdf figure
\end{verbatim}
Another common conversion tool is \texttt{pdftoppm}. The exact conversion program is not important; what matters is that the PNG is large enough to remain crisp at the width used by the article.
Do not use a screenshot of the editor as the production figure when a direct render is available. A direct render preserves line quality, mathematical text, and consistent margins.
\subsection{Step 7: use matching filenames}
Use descriptive filenames and keep the PNG and TikZ source basename closely related. For example:
\begin{verbatim}
EA07_intrinsic_321_frame_chain.png
EA07_intrinsic_321_frame_chain_tikz.tex
\end{verbatim}
This makes it immediately clear which source belongs to which rendered figure.
Avoid spaces in production filenames. Use letters, numbers, and underscores where practical.
\subsection{Step 8: upload both files to PhysicsLibrary}
Upload the PNG as the figure that the article will display. Also upload the TikZ \texttt{.tex} source in the article's file box so another editor can reproduce or modify the figure later.
The PNG and TikZ source should be treated as a pair:
\begin{itemize}
\item \textbf{PNG}: renderer-compatible publication image;
\item \textbf{TikZ source}: editable and reproducible master.
\end{itemize}
If the figure is revised, update both files so that the uploaded source continues to reproduce the published image.
\section{Including the PNG in a PhysicsLibrary article}
PhysicsLibrary currently recommends an explicit width for PNG and JPG figures. A renderer-friendly pattern is:
\begin{verbatim}
\begin{center}
\includegraphics[width=0.85\textwidth,keepaspectratio]{your-image.png}
\vspace{0.5em}
{\small Figure 1. Short plain-text caption.}
\end{center}
\end{verbatim}
Use a \textbf{bare filename} in \texttt{\string\includegraphics}. Do not put a local directory path such as \texttt{/mnt/data/} or a workstation-specific directory in PhysicsLibrary production source.
For example, use
\begin{verbatim}
\includegraphics[width=0.82\textwidth]{EA07_intrinsic_321_frame_chain.png}
\end{verbatim}
rather than
\begin{verbatim}
\includegraphics[width=0.82\textwidth]{/some/local/path/EA07_intrinsic_321_frame_chain.png}
\end{verbatim}
PhysicsLibrary's current renderer is generally more reliable with a centered image and plain-text caption than with a complicated floating \texttt{figure} environment. Avoid unnecessary \texttt{\string\caption}, \texttt{\string\label}, and \texttt{\string\ref} machinery when a simple centered figure is sufficient.
\section{Suggested visual conventions for physics diagrams}
These are recommendations rather than strict site requirements, but consistent conventions make a series of related figures easier to read.
\subsection{Frames and colors}
For diagrams involving several frames, a useful scheme is:
\begin{itemize}
\item original/reference frame: black;
\item first intermediate frame: blue;
\item second intermediate frame: green;
\item final frame: red.
\end{itemize}
Do not rely on color alone. Every axis should still carry an explicit label such as $x_A$, $y_1$, $z_2$, or $x_B$.
\subsection{Positive rotation arrows}
A curved angle arrow should point from the original axis toward the rotated axis for the positive physical frame rotation being illustrated. A separate small loop around the actual rotation axis can be helpful when a three-dimensional viewpoint makes the rotation plane difficult to see.
The loop must be drawn around the actual fixed or moving rotation axis, not merely near whichever axis is most convenient in the two-dimensional projection.
\subsection{Three-dimensional coordinate figures}
TikZ drawings are ultimately projected onto a two-dimensional page. For a three-dimensional frame diagram, there are two acceptable approaches.
\textbf{Exact projected geometry.} Compute the three-dimensional vectors from the actual rotation matrices and project those vectors into the TikZ plane. Use this approach when the exact relative geometry is part of the mathematical argument.
\textbf{Conceptual schematic.} Choose projected axis directions manually to make the moving-axis concept clear. Use this approach when the figure is explicitly explanatory rather than quantitative. Even in a schematic, the rotation sense, fixed axis, moving axis, and frame labels must still be physically correct.
If exactness matters, do not independently hand-place axes that are supposed to be related by one rotation angle. Compute them from the same rotation matrix first.
\section{A small reusable TikZ example}
The following source creates a simple passive-frame rotation sketch. It is intended as a starting pattern, not as a universal convention diagram.
\begin{verbatim}
\documentclass[tikz,border=8pt]{standalone}
\usepackage{amsmath}
\usetikzlibrary{arrows.meta}
\begin{document}
\begin{tikzpicture}[>=Latex,line cap=round]
\coordinate (O) at (0,0);
% Reference axes.
\draw[->,thick] (O) -- (3,0)
node[right] {$x_A$};
\draw[->,thick] (O) -- (0,3)
node[above] {$z_A$};
% Rotated axis.
\draw[->,very thick,blue] (O) -- (2.3,1.7)
node[above right] {$x_B$};
% Positive angle.
\draw[->,blue,thick]
(1.25,0) arc[start angle=0,end angle=36,radius=1.25];
\node[blue] at (1.5,0.45) {$\lambda$};
\end{tikzpicture}
\end{document}
\end{verbatim}
Compile this source, inspect the result, and then adapt the coordinate geometry to the physical problem being illustrated.
\section{Tools}
\subsection{Primary PhysicsLibrary TikZ editor}
\PMlinkexternal{TikZ Editor at tikz.dev}{https://tikz.dev/editor/}
should be the first choice for creating and iterating ordinary PhysicsLibrary TikZ figures. The surrounding
\PMlinkexternal{PGF/TikZ online manual}{https://tikz.dev/}
is also the primary syntax reference.
\subsection{Overleaf}
\PMlinkexternal{Overleaf}{https://www.overleaf.com/}
is useful when a full LaTeX project, file management, collaboration, or repeated compilation is needed. Its
\PMlinkexternal{TikZ package guide}{https://www.overleaf.com/learn/latex/TikZ_package}
contains introductory examples for lines, nodes, shapes, curves, and diagrams.
\subsection{TikzMaker}
\PMlinkexternal{TikzMaker}{https://tikzmaker.com/editor}
is a browser-based graphical editor that can be useful for constructing diagrams visually and obtaining TikZ code. It can be particularly convenient for quick circuit, geometry, and diagram layouts.
\subsection{Local LaTeX tools}
A local TeX installation is useful for final validation and batch rendering. Common choices include
\PMlinkexternal{TeX Live}{https://www.tug.org/texlive/}
and
\PMlinkexternal{MiKTeX}{https://miktex.org/}.
A local editor such as
\PMlinkexternal{TeXstudio}{https://www.texstudio.org/}
or Visual Studio Code with a LaTeX extension can be convenient for larger figure collections.
Local compilation is especially useful when a figure depends on extra TikZ libraries or when a precise PDF-to-PNG conversion is required.
\section{Common mistakes}
\subsection{Putting raw TikZ in the article body}
Do not assume that a \texttt{tikzpicture} pasted directly into a PhysicsLibrary object will render through l2h/LaTeX2HTML. For current production use, render a PNG and include the image instead. Upload the TikZ source separately in the article's file box.
\subsection{Uploading only the PNG}
A PNG is easy to display but difficult to revise exactly. Upload the TikZ source too. The goal is for future editors to be able to change an arrow, angle, label, color, or viewpoint without redrawing the figure from scratch.
\subsection{Uploading only the TikZ source}
The source is valuable, but current readers still need the renderer-compatible PNG. Upload both.
\subsection{Using a local path in the article}
Do not write:
\begin{verbatim}
\includegraphics{/home/user/project/myfigure.png}
\end{verbatim}
or any similar machine-specific path. Use the uploaded file's bare filename.
\subsection{Using arrows that visually contradict the equations}
For frame rotations, verify that arrow direction represents the physical rotation intended by the article. Do not reverse a physical right-hand-rule arrow merely because the associated passive coordinate matrix has the opposite numerical sign from an active vector rotation.
\subsection{Crowding labels and arrows}
If labels touch arrowheads, axes overlap unrelated text, or arrows run through boxes, adjust the TikZ coordinates before export. Renderer compatibility does not compensate for poor visual spacing.
\section{Publication checklist}
Before considering a TikZ-derived PhysicsLibrary figure complete, verify the following:
\begin{itemize}
\item The physics and sign conventions agree with the article.
\item The visible PNG was rendered from the uploaded TikZ source.
\item The PNG has a white or otherwise intentional background.
\item Axis arrows and angle arrows point in the intended directions.
\item Labels do not overlap arrows, boxes, or other labels.
\item Mathematical notation matches the article.
\item The figure remains readable when scaled to approximately 80--90 percent of the article text width.
\item The PNG filename contains no local directory prefix in the article source.
\item The PNG is uploaded to the article.
\item The TikZ \texttt{.tex} source is uploaded in the article's file box.
\item The caption is concise and preferably plain text.
\item The figure has been checked in the PhysicsLibrary preview before publication.
\end{itemize}
\section{Summary}
For current PhysicsLibrary production, TikZ should be treated as the \textbf{editable source language} for technical diagrams and PNG as the \textbf{renderer-compatible publication format}. Create and refine the source primarily with
\PMlinkexternal{tikz.dev/editor}{https://tikz.dev/editor/},
retain the source, render a clean PNG, upload both files, and include the PNG with a simple renderer-friendly \texttt{\string\includegraphics} block.
This workflow gives PhysicsLibrary the immediate compatibility of ordinary images without sacrificing the reproducibility and precision of source-controlled technical graphics.
\end{document}