README
¶
OneFit-Engine-plot
plot-go renders the Grace (xmgrace) project files OneFit writes - the
.agr/.agr-par plots of every fit - straight to PDF, EPS and SVG,
without Grace, Ghostscript or epstopdf. It is a batch renderer for the
part of the Grace format OneFit uses, not a clone of xmgrace; interactive
plots are the OneFit GUI's job.
Status: steps 1 to 6 of the plan below are done; step 7 is the OneFit GUI's Figures editor, in use and growing. What plot-go draws, and what it reads and keeps without drawing, is in docs/capabilities.md: a measured subset of Grace, not all of it; what is still to come, in docs/roadmap.md. On every corpus file plot-go matches gracebat within stated tolerances - primitive by primitive, and on the rendered page - not exactly; the tolerances are in docs/grace-behaviour.md ("How closely plot-go matches"). plot-go also takes gracebat's own command line - the one OneFit's C core gives Grace, recorded from real fits in testdata/gracebat-call* - and writes the EPS and a saved project. OneFit's C core uses it when installed, and the OneFit GUI draws its Figures with it.
go install ./cmd/plot-go
plot-go fit-curves-1.agr # -> fit-curves-1.pdf
plot-go -o plot.svg fit-curves-1.agr # format from the extension
plot-go -format eps fit-curves-1.agr # what OneFit's C core asks for
plot-go -o plot.png fit-curves-1.agr # cropped to the drawing, at 300 dpi
plot-go -dpi 600 -o plot.png fit-curves-1.agr # line art at 600 dpi
plot-go -fullpage -o plot.png fit-curves-1.agr # the whole page, as gracebat's PNG
plot-go -dpi 600 -o plot.tiff fit-curves-1.agr # lossless TIFF (.tif also accepted)
# gracebat's command line, as OneFit's C core calls Grace:
plot-go -settype xydy gnu0.da_ -nxy fit-curves-1 -param fit1.agr-par \
-hdevice EPS -hardcopy -printfile fit-curves-1.eps -saveall fit-curves-1.agr
PNG and TIFF are cropped to the drawing, as the PDF, EPS and SVG are, so they
drop straight into a document; -fullpage keeps the whole page instead (what
gracebat's PNG is). This holds for gracebat's command line (-hdevice PNG) too.
-dpi selects their resolution
(default 300); it does not affect PDF/EPS/SVG. TIFF uses lossless compression
and both formats record resolution metadata. Exports accept 1–2400 DPI and
at most 100 million pixels per page; choose a lower DPI for a large page.
Raster export needs one installed converter: Poppler (pdftoppm) is tried
first, then Ghostscript, then ImageMagick. On Windows, Ghostscript's console
programs gswin64c.exe and gswin32c.exe are found on PATH or in the standard
Program Files gs/gs*/bin folders, newest version first. Add a nonstandard
installation's bin directory to PATH. Windows' unrelated convert.exe is
never used. ImageMagick may also need Ghostscript and a policy allowing PDF.
Vector exports do not require any of these converters.
Plan
- Inventory: list every directive and text escape OneFit's files use
(
cmd/agr-inventory, results indocs/features.mdanddocs/inventory.md). - Parser and model for that part of the format.
- Renderer: page/viewport/world coordinates, normal and log axes, ticks and tick labels, xy and xydy sets, symbols, line styles, error bars, legend, strings, Grace text escapes.
- Reference tests: render a curated set of real files with plot-go and
with
gracebat, rasterise both, compare within a tolerance, in CI. - A command line compatible with the
gracebatcall OneFit's C core makes (-nxy,-settype xydy,-param,-printfile,-device,-saveall), writing PDF directly. - The C core uses plot-go when installed and falls back to
gracebat;onefite doctorreports which. - A live, editable preview in the OneFit GUI: the GUI shows plot-go's
SVG - the same drawing as the PDF - and edits (ranges, labels, styles,
texts) go into the
.agrand re-render. Both are Artistic 2.0, so the GUI can use plot-go as a library.
Install
Prebuilt binaries for Linux (amd64, arm64), macOS (Intel, Apple Silicon)
and Windows are attached to each release
(plot-go_OS_ARCH, with SHA256SUMS; releases/latest/download/plot-go_linux_amd64
is always the newest); put one on the PATH as plot-go. Or, with Go: go install github.com/fitteia/OneFit-Engine-plot/cmd/plot-go@latest.
Building from source requires Go 1.25 or newer; use the latest security patch
of your Go release. Release builds use the current stable Go toolchain.
The image/font and text libraries are pinned to golang.org/x/image v0.45.0
and golang.org/x/text v0.41.0, including fixes for malformed TIFF and SFNT
font inputs.
OneFit's C core (OneFit-Engine-C) uses plot-go for its plots when it finds
it on the PATH, and Grace otherwise; OFE_PLOTTER=grace forces Grace.
plot-go measures and draws text with the URW base-35 fonts, as Ghostscript
and gracebat do, when they are installed: fonts-urw-base35 on Debian and
Ubuntu; on macOS the onefite-go Homebrew formula installs them (in
Homebrew's share/fonts/urw-base35), as does brew install --cask font-urw-base35 (into ~/Library/Fonts); or any folder named in
OFE_URW_FONTS. Without them it
uses the Liberation fonts it carries: same widths, but legends and justified
texts can sit 1.5-2 points off gracebat's.
Clean-room rule
plot-go is distributed under the Artistic License 2.0 (see
LICENSE and NOTICE). Grace is GPL, so plot-go is
written from the format itself and Grace's documentation (the User's
Guide), never from Grace's source code. gracebat is used only as a
black box: its output is the reference the tests compare against.
Common text controls include underline and overline (\u…\U, \o…\O);
plot-go places overlines above the glyphs, correcting Grace's baseline-level
placement. Other controls include relative/absolute size changes
(\z{1.5}, \Z{1.5}), horizontal/vertical
shifts (\h{}, \v{}), baseline changes (\V{}), newlines (\n) and
hexadecimal characters (\#{b5}). They work wherever a Grace string is
drawn, including titles, axis labels, legends and point annotations.
Inline matrices (\t{}, \T{}), rotation/slant (\r{}, \l{}, \q,
\Q), colours (\R{}), pair kerning (\Fk, \FK), position marks
(\m{}, \M{}), and independent character/advance directions
(\dl, \dr, \dL, \dR) are also supported. Ligature toggles
(\Fl, \FL) are accepted; the supported Core-14 Latin-1 fonts do not
provide encodable ligature substitutions, matching the measured Grace output.
Additional installed TTF/OpenType fonts can be used by PostScript or full name.
Run plot-go -list-fonts to list discovered names. Set OFE_FONT_PATH to a
font file or a path-list of font directories to use fonts outside the usual
system folders. Their glyphs are embedded in PDF/EPS and outlined in SVG, so
viewers do not need the font installed. See fonts.md for
examples, search order, embedding restrictions and encoding limits.
The capabilities list and roadmap describe the supported controls and remaining font limitations.
Test data
testdata/corpus/: nine real OneFit plots chosen to cover the format's variety - normal and log axes, decimal and power tick labels, 3 to 7 sets, curve labels, every text escape, small symbols, and one malformed tick label format; they come from the OneFit-Engine test suites and the p96-10 sample that is already public in OneFit-Engine-assistant. Andstyle-*.agr, one per feature measured since (frames, patterns, legends, set fills, ...), each named in docs/grace-behaviour.md.testdata/ref/: gracebat's rendering of each, made byscripts/make-references.sh(gracebat -> EPS -> Ghostscript, the whole page at 144 dpi). Regenerating gives byte-identical files.
Development
go vet ./...
go test ./...
go run ./cmd/agr-inventory -o docs/inventory.md DIR...
PLOT_GO_CORPUS=DIR:DIR go test ./agr/ # also parse a whole local corpus
scripts/make-references.sh # needs gracebat and gs
Point annotations
The renderer supports Grace's avalue point labels: X, Y, X/Y, quoted
per-point text or the third numeric column. For example, s0 avalue on
and s0 avalue type 2 label each point with Y; type 4 uses a trailing
quoted label in its data row (1 2 "peak"). Font, color, size, rotation,
format, precision, prefix/suffix and viewport offsets round-trip through
saving. See the measured behaviour
and roadmap for release and Figures integration status.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agr reads Grace project files (.agr, .agr-par) - the part of the format OneFit writes (see docs/features.md) - into a Project.
|
Package agr reads Grace project files (.agr, .agr-par) - the part of the format OneFit writes (see docs/features.md) - into a Project. |
|
Package backend writes a draw.Drawing as a file: EPS (what OneFit's C core asks gracebat for), PDF (cropped as epstopdf crops gracebat's EPS), and SVG.
|
Package backend writes a draw.Drawing as a file: EPS (what OneFit's C core asks gracebat for), PDF (cropped as epstopdf crops gracebat's EPS), and SVG. |
|
cmd
|
|
|
agr-inventory
command
agr-inventory lists which parts of the Grace project format (.agr and .agr-par files) a set of files actually uses: every directive, reduced to its shape (graph/set numbers become #, numbers N, strings STR), with how many lines and files use it, and every text escape found inside strings.
|
agr-inventory lists which parts of the Grace project format (.agr and .agr-par files) a set of files actually uses: every directive, reduced to its shape (graph/set numbers become #, numbers N, strings STR), with how many lines and files use it, and every text escape found inside strings. |
|
grace-probe
command
grace-probe runs gracebat on a Grace project and prints what it draws, one primitive per line, in viewport units - the black-box measurements plot-go is built from (see AGENTS.md: gracebat's output, never Grace's source).
|
grace-probe runs gracebat on a Grace project and prints what it draws, one primitive per line, in viewport units - the black-box measurements plot-go is built from (see AGENTS.md: gracebat's output, never Grace's source). |
|
plot-go
command
plot-go renders a Grace project file (.agr) the way gracebat does, without Grace: to PDF, EPS, SVG, PNG or TIFF.
|
plot-go renders a Grace project file (.agr) the way gracebat does, without Grace: to PDF, EPS, SVG, PNG or TIFF. |
|
Package draw is the drawing plot-go makes of a page: paths and texts in viewport units (the page's shorter side is 1, origin at the bottom left), in the order they are drawn.
|
Package draw is the drawing plot-go makes of a page: paths and texts in viewport units (the page's shorter side is 1, origin at the bottom left), in the order they are drawn. |
|
Package figure builds figures: Grace projects of their own, composed from the plots OneFit writes for its fits (fit-curves-N.agr), kept apart from them so a refit never overwrites one.
|
Package figure builds figures: Grace projects of their own, composed from the plots OneFit writes for its fits (fit-curves-N.agr), kept apart from them so a refit never overwrites one. |
|
internal
|
|
|
afm
Package afm gives plot-go the metrics of the 14 standard PDF fonts: each character's advance width and ink box, from Adobe's Core 14 AFM files (adobe-core14/, distributed with Adobe's MustRead.html as its terms require; see NOTICE).
|
Package afm gives plot-go the metrics of the 14 standard PDF fonts: each character's advance width and ink box, from Adobe's Core 14 AFM files (adobe-core14/, distributed with Adobe's MustRead.html as its terms require; see NOTICE). |
|
drawcmp
Package drawcmp compares two drawings - plot-go's and gracebat's (read from its EPS by internal/eps) - primitive by primitive.
|
Package drawcmp compares two drawings - plot-go's and gracebat's (read from its EPS by internal/eps) - primitive by primitive. |
|
eps
Package eps reads the EPS that gracebat writes into a list of drawing primitives - paths, arcs and texts with their exact coordinates - so plot-go's drawing can be compared with gracebat's number by number.
|
Package eps reads the EPS that gracebat writes into a list of drawing primitives - paths, arcs and texts with their exact coordinates - so plot-go's drawing can be compared with gracebat's number by number. |
|
fontfile
Package fontfile finds additional TrueType/OpenType fonts by PostScript name.
|
Package fontfile finds additional TrueType/OpenType fonts by PostScript name. |
|
glyph
Package glyph gives the outlines of characters in standard and installed fonts, so text can be drawn as shapes - the same in every browser, whatever fonts it has.
|
Package glyph gives the outlines of characters in standard and installed fonts, so text can be drawn as shapes - the same in every browser, whatever fonts it has. |
|
Package raster exports PNG and losslessly compressed TIFF through an installed PDF converter, cropped to the drawing as the PDF, EPS and SVG are, or the whole page with Options.FullPage.
|
Package raster exports PNG and losslessly compressed TIFF through an installed PDF converter, cropped to the drawing as the PDF, EPS and SVG are, or the whole page with Options.FullPage. |
|
Package render draws a Grace project (agr.Project) the way gracebat does, into a draw.Drawing.
|
Package render draws a Grace project (agr.Project) the way gracebat does, into a draw.Drawing. |