Ballot Creator

From Scantegrity Wiki

The Scantegrity ballot creation tool allows users to take PDF images of their ballot and prepare them for use during the election. It should allow users to identify each contest and how it should be counted and to add audio clips for instructions, each contest, and each candidate.

The ballot creator does not create ballots, it merely allows the user to make the ballots election ready by adding important information to each race and correcting interpretation problems. PDFs are created using a "mark indicator" which is an oval the user copies and pastes into the PDF image to indicate that the voter should be able to mark at this location.

The output of the creator is a special pdf and a set of audio clips that are bound to a Ballot Definition files (BDFs). These elements are stored as a jar archive file or in a folder, and are intended to be the first files stored on the bulletin board.

Contents 1 Requirements 2 Design 2.1 Startup 2.2 Opening Files 2.3 Interface 2.4 Add a Contest 2.5 Adding an Audio Clip 2.6 Audio Clips 3 Known Error States 3.1 Audio clips are corrupted 3.2 Mark positions do not match selected contest type

[edit] Requirements

The creation tool has several requirements:

1. Must take PDFs as input.
2. Must produce a Ballot Definition File matching user input.
3. Output must identify contests and its contestants.
4. Output must identify the location for the serial number, and it should be the proper size depending on the size of the race.
5. Must allow user to add audio files to the ballot to match the contests and directions. Must allow user to indicate an order for directions and contests.
6. Output must be readable by the Scantegrity Election Manager, the Scanner, and the Election Verifier using the Ballot Definition File format that is part of an Election Definition File.
7. UI has to be user friendly, and should follow the Rules for User Interfaces.

[edit] Design

The following is a preliminary design. Because Ballot Creator is primarily centered around a user interface, we center our discussion around the user experience with the software. This should be followed up with a more formal description of specific design decisions at a later date.

[edit] Startup

The ballot creator will search for a usage file stored in the standard place for each operating system. This will allow it to load previous BDFs into the "Open Recent" menu with the names of the BDFs that are still stored at their reported locations. It will also modify it's "defaults" list with whatever the options selected from the most recent BDF.

If opened with a filename, the creator will attempt to load that file as a BDF. The file could be a PDF or the XML file describing the election.

[edit] Opening Files

If it is a PDF, it will search for an appropriate BDF or XML file that might match the name of the PDF. If it finds one, it will load that BDF. If it doesn't, it will tell the user and ask if the user intends to create a new BDF or if the user can tell it where the appropriate BDF is located.

If it is an XML file, it will load the BDF. Loading a BDF verifies that the files exist and performs an integrity check on the files to look for changes. If it finds anything, it will notify the user.

[edit] Interface

The creator interface is focused around a display window, which allows for the following (sticky) controls:

• Pan - Allow the user to click on the image and move around.
• Zoom In/Out - Allow the user to left click or select an area to zoom and and to right click an area to zoom out.
• Add a Contest (A select box) - Allows a user to select an area on a screen and add a contest to the ballot.
• Add an Audio clip (also a select box) - Allows a user to select instructions to be played for the currently selected contest or ballot.
• Ballot On/Off - Allows a user to turn off the ballot image to enable her to see the detected races and candidate names.

Non sticky controls allow the user to move forward and backward through the pages of the ballot.

To the side, a summary screen that details each race and if there is an audio clip is displayed in a tree format for each page of the ballot.

In the following sections, the controls for adding a contest or audio clip are explained.

[edit] Add a Contest

To add a contest, the user draws a box around the desired contest. This initiates a detection algorithm that will take the following actions:

1. There are X text boxes, and X mark indicators. The contest is a plurality, N choose M, or Approval voting election. A box will appear that allows the user to select the appropriate contest type.
2. There are X text boxes, and Y*X mark indicators, where Y is some number > 1. The contest is ranked choice, and could be an Instant Runoff, Condorcet, Borda, or Range voting election. A box appears that allows the user to select the appropriate contest type.
3. There are X mark indicators but no text, or the number of text boxes does not match. The ballot creator asks the user to choose which election method, and provides a way to enter the candidate names manually.
4. Another condition occurs, and the software attempts to deal with that problem or reports and error and allows the user to try again.

In 1 and 2, the detected names of the candidates are also displayed in the contest selection window. Additionally, after the user has finished her selection, the application will draw numbers and shaded boxes around the selections it believes are correct. The contest selection window will allow the user correct problems by clicking on each race and highlighting the places belonging to each position/rank. The contest selection window will also allow the user to pick an audio file for each Candidate name, if it cannot find a file of the same name in the same directory as the PDF file. 3 is identical to 1 and 2 with the exception that race type is chosen before the candidate name boxes are displayed.

[edit] Adding an Audio Clip

This button only works for instructions that are played before or after each contest. The user must click on the appropriate contest on the side bar before being allowed to select something in the image. A file browser with an audio preview option will appear when adding an audio clip.

[edit] Audio Clips

A small graphic will be displayed next to each element with an audio clip associated with it. Clicking on this graphic will play the audio clip using the default system sound settings.

[edit] Known Error States

[edit] Audio clips are corrupted

Report a passive error and treat the operation as if the user canceled it.

[edit] Mark positions do not match selected contest type

If possible, fill in the missing locations. If not, report a passive error and allow the user to try again.