barnhunt 1.2.1rc3

Helpers for drawing Barn Hunt course maps using Inkscape

Barn Hunt Map Helper

This is a helper script Jeff uses for drafting Barn Hunt course maps.

It does a bunch of stuff, but the important bit is that it exports PDF versions of maps from Inkscape SVG files.

I draw all the maps for a given ring (for a day or weekend) in a single Inkscape drawing. Various maps (for different trials/classes, build map, rat-maps, base maps, etc.) are generated by hiding and unhiding appropriate layers in the drawing and exporting to PDF.

This program automates that process.

Requirements

This program requires Python, version 3.7 or higher to run.

It "should" work with all versions of Inkscape, 0.9x through 1.2.1.

I use this program on Linux, however the package now includes a GitHub CI workflow that performs rudimentary testing on Windows and macOS, so there’s a moderate chance it might "just work" on those platforms. (Due to a dependency on the pikepdf package, it should work on x86_64-based Macs, but may not work on Macs that use Apple silicon. If pikepdf compatibility is an issue for you, let me know — it’s probably fixable.)

Installation

Windows

We now publish a compiled version of the program for Windows (which may even work.) Using this version has the advantage that Python is not required to be installed. (And even if Python is installed, this version may work-around some bugs having to do with the various different ways that Python can be installed on on Windows computer.)

1. Browse to our releases page. Select a release, and look down in the Assets section of the release page. (You may have to click the triangle to expand the Assets section.)

2. Download the MSI installer (the filename should end with .msi — e.g. Barnhunt-1.2.0.49-x86_64-pc-windows-msvc.msi). The file is not signed, so you may have to click through some nasty warnings about "unrecognized, potentially dangerous" files.

3. Once downloaded, open (double-click) the file you just downloaded. Hopefully and installer dialog should open. Accept the default choices.

4. Now open a terminal command-line window. Type barnhunt --version. If all is good, barnhunt should report its version. Run barnhunt --help for the help screen.

Linux (or Windows with Python installed)

As this package is published to PyPI it may be installed into a virtualenv using pip. It is suggested that you use pipx to combine those two steps.

A basic outline of how to proceed:

1. Install python if it is not already installed. (Version 3.7 or greater is required.)

2. Install pipx. This might look like:

   python3 -m pip install --user pipx
   python3 -m pipx ensurepath
   

3. Install barnhunt.

   pipx install barnhunt
   

How to Use

Sadly, this program is currently quite under-documented.

The functions of the basic sub-commands and command-line options are tersely documented via the --help option. Try:

barnhunt --help

and

barnhunt pdfs --help

for starters.

If you get stuck, kick me!

Author

This package was written by Jeff Dairiki, BHAJ-221A, [e-mail].

---

Changes

Release 1.2.1rc3 (2023-08-04)

Bugs Fixed

• Fix crash when clone refers to a hidden layer.

Internal API changes

• Inkscape.svg.ancestor_layers(elem) now includes elem in the returned results if elem is an Inkscape layer element. Previously, the search for ancestor layers strated with elem's parent.

Release 1.2.1rc2 (2023-06-06)

New Features

• Provide access to RDF metadata in the SVG source in string templates. E.g. the document description may be interpolated via {{ rdf['dc:description'] }}.

Bugs Fixed

• Fix parsing of version strings reported by pre-release versions of Inkscape.

Release 1.2.1rc1 (2023-05-22)

(There was no final release of 1.2.0. It is a long story. I mistakenly committed a couple of files to LFS. To clear out LFS storage for a GitHub repo, one has to delete the whole repo. As a result, the workflow $GITHUB_RUN_NUMBER has reset. Thus a micro-version bump is required to keep those PyOxidizer windows build version numbers — <major>.<minor>.<micro>.<run-number> — monotonic.)

CLI Changes

• The --inkscape-command, --processes and --shell-mode-inkscape options have been moved from the barnhunt pdfs subcommand to the man barnhunt command group.

• And new debug-info subcommand has been added to display various information about the installed version of the barnhunt command and its execution environment.

• The --dump-loaded-modules option has been removed. The functionality is still available by setting the $BARNHUNT_DUMP_LOADED_MODULES environment variable to a non-empty value.

Bugs Fixed

• Fixed exception in barnhunt.cli.default_2up_output_file during shell-completion for barnhunt 2up.

Release 1.2.0rc6 (2023-04-27)

• Build an Windows executable and installer using PyOxidizer. The .msi installer should be downloadable from the Releases page.

• Added a --dump-loaded-modules option which causes barnhunt to write a list of all loaded modules the current working directory. (This is a development tool, not generally useful to most users.)

• Hardwire the distribution version into barnhunt.__version__ rather than deducing it via importlib.metadata. This allows us to monkey with the version we report from the PyOxidizer-built Windows executable so that it indicates the MSI build version as well as the distribution version.

• Convert package from setuptools to PDM.

Release 1.2.0rc5 (2023-03-05)

Bugs Fixed

• When there was a visible “clone” (<svg:use> element) that referenced a source on a hidden layer were being pruned from the SVG before conversion to PDF. (When exporting an SVG, hidden layers are omitted from the SVG — this speeds Inkscape up considerably when there is a large amount of hidden content.) Now we detect hidden layers that contain source material for clones, and retain them in the SVG file.

• Add a cruft pattern to ignore “Gtk-WARNING"” messages that have started appearing since I installed Inkscape from Inkscape’s ppa.

• Fix tests to workaround segfault from pikepdf 7.0.0, 7.1.0, and 7.1.1. (See [pikepdf/pikepdf#452].)

[pikepdf/pikepdf#452]: https://github.com/pikepdf/pikepdf/issues/452).

Release 1.2.0rc4 (2023-01-09)

Support python 3.11.

Bugs

• Shell-mode runner: fix readline/pexpect disagreement with respect to horizontal scrolling of long lines. In some cases, when Inkscape is compiled to use GNU readline, long input lines will be scrolled horizontally (even when stdin is not a tty). This messes with pexpect's head. We've now added some basic tests for this, and set some environment variables to try to convince readline not to do the scrolling.

Testing

• Test under python 3.11
• Fix tests for Windows environments where $APPDATA is not set
• Fix tests for error message changes in packaging>=22

Release 1.2.0rc3 (2022-10-19)

Extension/Symbols Installer

• Make code for deducing Inkscape profile directory more robust. (There's now a beter chance this will actually work on Windows.)
• Support setting Inkscape profile directory via $INKSCAPE_PROFILE_DIR.

Release 1.2.0rc2 (2022-10-17)

Extension and Symbol Set Installation

• This release add a barnhunt install (and uninstall) sub-command to simplify installation of the inkex-bh Inkscape extensions and bh-symbols symbol sets.

Testing

• Update to mypy==0.982 for testing. Fix spurious mypy errors.

Release 1.2.0rc1 (2022-08-31)

First public release to PyPI. Moved project to GitHub.

• Dropped support for python 3.6
• Changed license to GPL version 3
• We now do rudimentary testing under Windows and macOS.

Dependencies

• Use pikepdf instead of pdfrw to manipulate PDFs. (Pdfrw seems not to be very actively maintained.) The only possible downside of this is that pikepdf is not pure-python. It claims to be easily installable on Windows and x86_64 Macs, but is not (easily) installable on Macs with Apple silicon.

• Generated PDFs are now linearized and compressed.

• Add test dependency on pdfminer.six (but drop dependency on PyPDF2).

Compatibility

• Refactor barnhunt.inkscape.runner to support running Inkscape >= 1.0 (as well as continuing to support Inkscape 0.9x).

• Add --inkscape-command parameter to the barnhunt pdfs command to specify the name/path of the Inkscape binary to run to export PDFs. This also supports setting the Inkscape executable via the $INKSCAPE_COMMAND environment variable. Default executable is not inkscape.exe on Windows (and inkscape everywhere else).

• Use pexpect.popen_spawn.PopenSpawn instead of pexpect.spawn to run Inkscape in shell-mode. Due to pexpect.spawn's use of ptys, it will not work on Windows.

• MacOS: our code for running Inkscape in shell-mode appears to be broken. For now, on macOS we default to not using shell-mode.

Packaging

• Added a stub barnhunt.__main__ module to allow running via python -m barnhunt.

Testing

• Add type annotations.

Bit Rot

• Fix up tests to address deprecations in PyPDF2.

Release 1.1.0a1 (2022-03-08)

"Base Map" support

Add ability to mark layers for exclusion from particular output files.

This adds the ability to list multiple comma-separated output base filenames for a given overlay. E.g. A layer with label "[o|build_notes,base] Build Notes" will define an overlay which will generate maps in two separate output files.

Tagging a layer with [!output-basename] will exclude that layer from any maps which are directed to the specified output filename.

Tagging a layer with [=output-basename] will include that layer from any maps which are directed to the specified output filename, while excluding all other sibling layers not explicitly tagged to be included in that output file.

Release 1.0.1 (2021-11-10)

Diagnostics

Barnhunt pdfs now issues a warning when generating PDFs from an SVG file which does not have an explicit random-seed set.

Bugs Fixed

Open SVG files in binary mode in order to let the XML parser figure out the encoding from the XML declaration.

Release 1.0 (2021-11-10)

Support python 3.10.

Random Seed

The way the random seed (used for generating random rat numbers) for each SVG layer is computed has been changed in a backward-incompatible way. This was done so that rat numbers can be kept from changing when an SVG source file is copied or edited in such a way that the device and/or inode of the file changes.

Now, the file-level random seed (an integer) is read from the bh:random-seed attribute of the root svg element of the SVG file. If no bh:random-seed attribute is set, the file-level seed is computed by hashing the device and inode numbers of the SVG file.

The layer-level seed is formed by hashing the file-level random seed with the XML id of the layer.

(Formerly, the layer-level seed was form by hashing a triple of the file-level seed (which was always zero), the hash of the SVG files device and inode, and the id of the layer.)

A new barnhunt random-seed sub-command has been implemented to help with setting the random seed for SVG source files.

Bit-rot

Address DeprecationWarning: 'contextfunction' is renamed to 'pass_context' from Jinja2. Require Jinja2>3.

OCDisms

Run pyupgrade --py36-plus on source.

Release 0.5 (2021-05-04)

Make -o option to 2up sub-command optional.

Remove support for python < 3.6.

Release 0.4 (2019-02-25)

New Sub-Command: 2up

New 2up sub-command to format PDFs for 2-up printing. Pages are pre-shuffled so that the 2-up pages do not need to be shuffled after cutting.

Release 0.3 (2019-02-20)

barnhunt pdfs

• Multi-page output support.

  There is a new syntax to specify the output file basename for an overlay. Multiple overlays which specify the same output file will all be saved to the same file.

• It is now possible to render course maps from multiple SVG files in a single invocation. (Just list all the files to be rendered on the command line.)

Tests

• test_layerinfo.test_layerflags_str: Fix test to deal with arbitrary ordering of enum.Flag flags.

Release 0.2 (2018-11-07)

Templating

• Do not expand text within hidden layers. This avoids generating error messages (e.g. "'overlay' is undefined") due to template expansion of unused text.

• Add optional skip argument to the random_rats function. This allows the generation of more than one set of stable random rat numbers per layer. E.g. random_rats(skip=5) will generate a set of random number totally uncorrelated to that generated by random_rats(). Using skip has the advantage over using seed=None that the results are stable and do not vary from render to render.

Release 0.1 (2018-11-07)

• Python 3.7 is now supported.

• The template for the output filename has been generalized to work sensibly in the case where overlays are nested more than two deep.

Templating

• Added new attributes to layers:

  layer.is_overlay Boolean. True if layer is an overlay.

  layer.lineage Sequence starting with layer and including each parent layer in turn.

  layer.overlay Returns the nearest overlay layer. If the layer is an overlay, layer.overlay returns layer, otherwise it returns the nearest parent layer which is an overlay. If the layer is not contained within an overlay, returns None.

• Added new values to context when expanding text in SVG:

  overlays A list of all overlay layers in the lineage of the text element, in order from outermost to innermost.

  course The outermost overlay layer. (Equivalent to overlays[0].) This value already existed in the context used for filename expansion.

  overlay If the element is at least two overlays deep, this is the innermost overlay. Otherwise it is unset. This value already existed in the context used for filename expansion.

• Added new values to context when expanding output filenames:

  overlays A list of all overlay layers in the lineage of the overlay being expanded.

Bugs

• Templating: the safepath filter would fail with a TypeError if applied to anything but a string. Now it coerces its argument to text.

• Templating: (New style) layer flags in parent layers were not being removed from the layer labels. (E.g. "{{ layer.parent.label }}" was expanding to "[o] Some Overlay", when it should expand to "Some Overlay".)

• Pexpect==4.4.0 appears to have a subtle brokenness when searchwindowsize is set to something other than None. The problem seems to be in pexpect.expect.py, and is triggered when multiple chunks of output are read before a match is found.

Bit-Rot

• Use log.warning, rather than the deprecated log.warn.

Release 0.1a12 (2017-02-09)

• Remove tags from layer.label when expanding templated text in SVG file.

Release 0.1a11 (2017-02-01)

• Add --version command line option

Pager for coords

• A fancy pager (poor man's less) has been added for viewing the output of the barnhunt coords sub-command. If any of sys.stdin or sys.stdout is not a tty, then the pager will be disabled.

• Since there is now a fancy pager, the default for --number-of-rows has been increased to 1000.

Release 0.1a10 (2017-01-30)

Things still to be fixed

Things still to be fixed: I'm pretty sure things are direly broken if a drawing contains no overlays, and somewhat broken if a drawing contains more than two layers of overlays. The problems have to do with how the output PDF filenames are determined...

New layer flag scheme

New scheme for marking overlay and hidden layers. One can now set bit-flags on layers by including the flags in square brackets at the beginning of the layer label. I.e. a label like "[o] Master Trial 1" marks the layer as an overlay layer, while "[h] Prototypes" marks a hidden layer.

If no layers have any flags, barnhunt pdfs will fall back to the old name-based heuristics for determining hidden and overlay layers.

Release 0.1a9 (2017-01-03)

• When exporting PDFs, run inkscape with --export-area-page.

Packaging

• Fix MANIFEST.in. Tests were not being included in sdist.

• Add url to package metadata.

Release 0.1a8 (2018-01-03)

• Ignore ring layers when identifying course layers. (Now a layer labeled “C8 Ring” will not be treated as a course layer.)

• pdfs: default --output-directory to . (avoiding exception when no explicit output directory is specified.)

Release 0.1a7 (2017-11-18)

• Change barnhunt coords so that it omits duplicate coordinates in its output. Also increase the default for --number-of-rows to 50 and add the --group-size parameter to separate output into groups.

Release 0.1a6 (2017-11-15)

• Templating: LabelAdapter now stringifies to the layer label, and FileAdapter now stringifies to the file name.
• More refactoring, more tests
• Run several inkscapes in parallel. This results in a major speedup.

Release 0.1a5 (2017-11-13)

• Expand text in SVG file.
• Add tests.
• Major code refactor.

Release 0.1a4 (2017-11-10)

PDFS

• Log unexpected output from inkscape.

• Add --no-shell-mode-inkscape option to control whether shell-mode inkscape optimization is used.

Release 0.1a3.post1 (2017-11-10)

PDFS

• Reverse order that layers are considered. (Layers are listed from bottom to top in the SVG file.)

Release 0.1a3 (2017-11-10)

PDFS

Replace spaces and other shell-unfriendly characters with underscores in output file names.

Release 0.1a2 (2017-11-09)

Add sub-commands for generating random numbers.

Release 0.1a1 (2017-11-07)

Initial release.