Skip to content

Latest commit

 

History

History
111 lines (83 loc) · 4.54 KB

README.md

File metadata and controls

111 lines (83 loc) · 4.54 KB
Raw

Ballot Studio

System for designing, printing, and scanning paper ballots.

Ballot Studio is designed to be a core piece of an open source voting system.

Getting Started

Ballot Studio is in two parts, a Python back end that draws PDF ballots, and a go middle layer that runs a web app with login and database and editing ballot data and scanning ballot images.

Python Setup

  • python3 -m venv bsvenv
  • bsvenv/bin/pip install fonttools Flask mercurial
  • (cd python && ../bsvenv/bin/pip install -e .)
  • bsvenv/bin/hg clone https://hg.reportlab.com/hg-public/reportlab
  • (cd reportlab && ../bsvenv/bin/pip install -e .)
  • get the resources blob (images and fonts):
    • curl -O https://bolson.org/ballotstudio/resources.tar.gz
    • tar zxvf resources.tar.gz
  • Liberation fonts may have newer versions available at https://github.com/liberationfonts/liberation-fonts/releases

Go Setup

  • Install Go from https://golang.org/dl
  • make
  • install poppler-utils to rasterize pdf, one of:
    • apt-get install -y poppler-utils
    • yum install -y poppler-utils
    • git clone https://github.com/brianolson/poppler.git
      • See Development dependencies below
  • ./ballotstudio -flask bsvenv/bin/flask -sqlite bss -debug
    • open the login link shown in initial status log lines

Development

Dependencies:

  • https://github.com/brianolson/login
    • Local user/pass and oauth2 login
  • https://github.com/brianolson/httpcache
    • Simple local http cached used by login
  • https://github.com/brianolson/poppler
    • Fork of poppler with pdftoppm that does multiple pages in one operation
    • git clone https://github.com/brianolson/poppler.git
    • `(cd poppler && git checkout png-multi-block && mkdir build)``
      • redhatish:
        • sudo yum install -y cmake3 freetype-devel fontconfig-devel libjpeg-turbo-devel openjpeg2-devel libtiff-devel
        • (cd poppler/build && cmake3 .. && make pdftoppm)
      • debianish:
        • sudo apt-get install -y libjpeg-dev libopenjp2-7-dev libfreetype-dev libfontconfig-dev
        • (cd poppler/build && cmake .. && make pdftoppm)
    • copy poppler/build/utils/pdftoppm to somewhere at head of PATH to be found by cmd/ballotstudio/drawsub.go

Developing the Python Draw Server

ballotstudio will normally automatically start and stop the draw server. It can be run on its own with:

FLASK_ENV=development FLASK_APP=ballotstudio.app flask run

ballotstudio can be given the option -draw-backend http://127.0.0.1:5000/ to point to that at Flask's default port 5000.

  • http://127.0.0.1:5000/demo.pdf - demo ElectionReport drawn to PDF
  • http://127.0.0.1:5000/demo.bubbles.json - bubble positions
  • http://127.0.0.1:5000/demo.js - ElectionReport built by draw/demorace.py
  • http://127.0.0.1:5000/random.pdf - Random 10-locality election
  • http://127.0.0.1:5000/random.pdf?parties=3&counties=2&towns=10&town-contests=1&county-contests=1&top-contests=2&cand-min=3&cand-max=9

Demo flow for creating a randomly marked ballot for an election:

# use the basic demo race
python3 -m ballotstudio.demorace > rr.json
# OR create a random election with 10 towns, 2 counties, 1 state
python3 -m ballotstudio.randrace > rr.json
# create random vote picks for that election
python3 -m ballotstudio.randvote < /tmp/rr.json > /tmp/rv.json
# draw out all the ballot styles to pdf files
mkdir -p /tmp/rrp
rm -f /tmp/rrp/*pdf; python3 -m ballotstudio.draw --mark /tmp/rv.json --outdir /tmp/rrp /tmp/rr.json

Production Notes

The draw server should can be run by gunicorn for a production environment. ballotstudio would be given a -draw-backend http://localhost:port/ option to point at the gunicorn server.

NIST 1500-100 extensions

NIST 1500-100 (version 2) is a specification on election results reporting, but is used here because it has all the structural information about candidates and contests and the election as a whole. We extend it with a few additional fields about ballot layout and rendering.

"ElectionResults.BallotStyle"

Optional field "PageHeader" is a string that would be rendered at the top of each page. For example:

Header Election Name, YYYY-MM-DD
Precinct 1234, Some Town, Statename, page {PAGE} of {PAGES}

\n newlines within the text will be rendered. Templated fields within the text are:

  • {DATE} the end date of the election
  • {DATES} the date range of the election
  • {PAGE} the current page number
  • {PAGES} the total number of pages
  • {PLACE} the smallest juristictional name of the election (town/city)
  • {PLACES} a string of place names, e.g. "state, county, city"