# Barn Hunt Map Helper

[![Test status badge](https://img.shields.io/github/actions/workflow/status/barnhunt/barnhunt/ci.yml?label=tests)](https://github.com/barnhunt/barnhunt/actions/workflows/ci.yml)
[![Latest version badge](https://img.shields.io/pypi/v/barnhunt.svg)](https://pypi.org/project/barnhunt/)
[![Supported Python versions badge](https://img.shields.io/pypi/pyversions/barnhunt.svg)](https://pypi.org/project/barnhunt/)
[![Supported Inkscape versions badge](https://img.shields.io/badge/Inkscape-0.9x%E2%80%931.2.2-blue.svg?logo=inkscape)](https://inkscape.org/)
[![Development status badge](https://img.shields.io/pypi/status/barnhunt.svg)](https://pypi.org/project/barnhunt/)
[![Trackgit-views](https://us-central1-trackgit-analytics.cloudfunctions.net/token/ping/lhapwefdbvler7yp5dsl)](https://trackgit.com)

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](https://github.com/barnhunt/barnhunt/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](https://pypi.org/project/barnhunt/) it may be installed into a
[_virtualenv_][venv] using [`pip`][pip]. It is suggested that you use
[`pipx`][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:

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

3. Install `barnhunt`.

   ```sh
   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:

```sh
barnhunt --help
```

and

```sh
barnhunt pdfs --help
```

for starters.

If you get stuck, kick me!

## Author

This package was written by Jeff Dairiki, BHAJ-221A, <dairiki@dairiki.org>.

----

[Inkscape]: https://inkscape.org/ (The Inkscape home page)
[Barn Hunt]: https://www.barnhunt.com/ (Barn Hunt — a fabulous sport for dogs)
[python]: https://www.python.org/ (The Python home page)
[venv]: https://docs.python.org/3/library/venv.html
(Python venv module documentation)
[pipx]: https://pypa.github.io/pipx/ (The pipx home page)
[pip]: https://pip.pypa.io/en/stable/ (Documentation for pip)
[pikepdf]: https://pikepdf.readthedocs.io/en/latest/installation.html
(The Installation section of the pikepdf documentation)
