Instructions for TurfCutterGM
  1. The Basics
    1. What is TurfCutterGM?
      2. TurfCutterGM is a tool for campaign field staffers to cut hours out of their lives that would be otherwise spent ordering and cutting up paper lists. Using Google Maps, TurfCutterGM allows you to point-and-click your way to creating walk lists.
    2. How does it work?
      3. TurfCutterGM asks for your list of houses in one area. Perhaps you give the program 400 people who you want your volunteers to visit; those 400 people live at 300 distinct addresses. TurfCutterGM will plot those 300 points and let you divide them anyway you want into, say, 6 routes of 50 houses. You then get the data back from TurfCutterGM with the route information appended, and you're all set to go. (For technologically oriented folk: TurfCutterGM is written primarily in Javascript, with some PHP.)
    3. Does it work well?
      4. Well, I would like to think so. But, the features that make TurfCutterGM special are:
      • Selecting a large group of points at a time by drawing boundaries around them
      • Auto-sorting of an entire route to give a reasonable approximation of the correct route
      • Drag-and-drop of one or more points for easy fine-tuning or route order
      • User-defined route colors and user-defined viewing options so you and cut turf the way you want to.
    4. What are the system requirements?
      5. Currently, I have tested TurfCutterGM only on Windows, using the Internet Explorer (v6), Firefox (v1.5), and Opera (v9) browsers. You need to disable pop-up blockers for TurfCutter to work correctly. (Don't worry, there are no advertisements on this page.)
      Please let me know what the status of Turfcutter's functionality is on other browsers and operating systems.
    5. Who can use TurfCutterGM?
      6. You, and anyone else. The program is completely free and is licensed as open source under the GPL.
  2. Using TurfCutterGM
    1. Preparing and Uploading Data
      1. Preparing the Data
        2. TurfCutterGM needs data from your voterfile software to work. Simply export your data in a comma-separated format to a file on your local machine. Specifically, do the following:
        • Separate fields with commas (,)
        • Enclose strings in double quotes ("")
        • Include header row with field names
        • Include a both a unique ID and (if possible) household ID.
        • Include longitude and latitude. (This will change in later versions.)
        • Limit the data to at most 1,000 addresses
        If you wish to use the Auto-sort feature, include street number and street name as well.
      2. Uploading the Data
        3. Simply click on "Browse" and choose the file you wish to import. Then click on "Upload CSV file". A pop-up window should open showing you the fields that are specified in your data. Match them up with the field names that TurfCutterGM understands. If you do not have a household ID field, use your unique ID. Next click "plot my points" and your points will be plotted. If the browser warns you about resending data, click the "retry" (IE) or "OK" (Firefox) option.
      3. Geocoding the Data
        4. Geocoding is now available, through Emad Famous' free tool. Please use geocoding only when testing TurfCutterGM. If you decide to use TurfCutterGM for your campaign, it is highly recommended that you bulk-geocode all of your data. Currently, you don't see the geocoding on the back-end, though this will change.

        Many vendors offer this geocoding service, but I would check out geocoder.us, who says that they will bulk-geocode data (for non-commercial purposes) for free. I'm not just recommending this course of action for my benefit: geocoding 100 data points takes about 1 minute, and as this is a free service, not necessarily the most reliable. Save yourself headaches ahead of time and get your data geocoded by professionals.

    2. Choose the Number of Routes
      3. Enter the number of routes you plan to create out of the imported addresses next to Number of routes:. You can change this value at any time.
    3. Selecting Points
      4. You now need to select points for your first route by changing the map mode. The default mode is browse map; you cannot select points in this mode. What you can do is click on points and view their information.

      The second mode is clicking points mode. Simply click points to select them. Hold down the shift or ctrl keys on your keyboard to select multiple points at a time.

      The final mode is drawing route boundaries mode. To use this mode, click anywhere on the map: a marker will appear. This marker indicates the first corner of your boundary. If you click again, you'll see a line drawn: this is the first side of your boundary. Continue drawing lines until you are ready to complete your boundary. To complete the boundary, click on the original point (labeled "S" for "start"). If you make a mistake, click the "Undo" button next to the upper-left-hand corner of the map and you last segment will disappear. Boundary segments are allowed to cross -- points in the interior of the boundaries when the region is completed will be selected.

      Alternatively, you can select points of an existing, select all unassigned points, select no points, or select all the points. These options are available in the selecting drop-down.

    4. Assigning points to routes
      5. Once you've selected the points you wish to be in the next route, simply choose the desired route number next in the Assign selected points to Route: drop-down. Changing the selected route in this drop-down will automatically show you the route characteristics. Check the route characteristics before you assign the points (using the Assign button) to make sure you are not performing an undesired action, such as appending points to an existing route.
    5. Route Characteristics
      6. Once you've assigned points to a route, you can view the characteristics of that route by selecting the desired route in the Show info and order points for route drop-down. In this section, you can change the color of your route and order the route's points. The Zoom To will pan the map to the center of the routes points.
      1. Route Color
        2. Change the route color using the Color of route markers drop-down. Two routes can be the same color.
      2. Ordering Points Manually
        3. The Ordering of points pane displays the current order of the points in the route. Points should be ordered in the manner easiest to walk them. The default order will probably not be appropriate for walking, so you should re-order the points. One way to order the points is to drag-and-drop the points in the order pane. A second method is to use the four movement buttons to the right of the pane. These buttons will move the selected points either: to the top of the order, up one slot in the order, down one slot in the order, or to the end of the order. The markers on the map will change to reflect this new ordering. Selecting points to move (either via drag-and-drog or movement buttons) is the done in the same manner as the Selecting Points section, with one addition. In the Ordering of points pane, points can be selecting by clicking on their address bars; the shift and ctrl perform their usual function, allowing you to select multiple points at a time. Selected points will be highlighted both in the pane and on the map.
      3. Ordering Points Automatically
        4. Ordering 50 points manually can be a tedious process. To alleviate this burden, you can order the points automatically. The simplest way to achieve this is to select entire route in the Auto-sort drop-down. This auto-sorts all the points in your selected route, keeping the first point the same. Therefore, it is recommended that you manually choose the first point in your route and then click the Sort button. Alternatively, to sort only a subset of the route, select the desired subset of points, and choose Only selected in the Auto-sort drop-down. (The points in the subset must all be next to each other in the route order to begin with. And, again, the first point in the subset will remain the first point in the sorted result.)

        Auto-sort algorithm. The auto-sort algorithm is a simplistic procedure, known as a "greedy algorithm" in computer science. Given the current point in the order (Point A), the algorithm chooses the next point by first computing the following values:

        • The Euclidian distance from Point A to the nearest point that is on the same side of the same street as Point A
        • The Euclidian distance from Point A to the nearest point that is on the same street as Point A
        • The Euclidian distance from Point A to the nearest other point
        These values are compared, with penalties given to points not on the same side of the street as Point A, and points not on the same street as point A. These penalties can be set by administrators who install TurfCutterGm on their own server. The current penalties for this version are: 200% of the distance for non-same-street-side points and 400% of the distance for non-same-street points.
    6. Exporting Data
      7. Once all your routes have been defined, simply click on the Export button in the upper-right-hand corner. This will open a pop-up and your browser will automatically download your original data with two columns appended: Route Number and Route Order. Import this data back into your voter file using those fields to properly order your walklist. And voila (!), no more cutting physical paper.
    7. Display and Print Options
      8. Clicking the arrow to the right of Options will display the display and print options. These options are especially useful if you want to print a "cover sheet" for each route. To print the cover sheet for a route do the following:
      • Set display assigned points to only when active
      • Set display of unassigned points to hide
      • Show the information for the desired route by using the drop-down.
      • Set your page setup to print to landscape and fit to one page.
      • Print the page using your browser: only the map will be visible.
  3. Installing TurfCutterGM on Your Own System
    4. This section will be completed soon. For now, please see the development page.
  4. Troubleshooting and Bug Reporting
    1. Do I need to have latitude and longitude on my data?
      2. Yes, as of now, you must geocode your data. If this project is popular, a separate geocoding module will be added in the future.
    2. Why won't my data export?
      3. Cookies are being used to transfer data on the routes. Some browsers disallow cookies over a certain size. This issue is being actively resolved.
    3. Why is the program so slow?
      4. Use Firefox or Opera as your web browser; both are clearly faster than Internet Explorer, and Opera appears to be slightly quicker than Firefox at rendering and sorting points. A faster Internet connection will also speed the process of rendering points on the map (since the program has to contact Google). If the program is still too slow, try uploading less data.
    4. I found a bug!
      5. First, thank you for testing out the program. Please email the problem you found to turfcuttergm@mindlessphilosopher.net .
    5. I'd like to help
      6. Great! Specifically, I'd like help producing a PDF-creation module and a geocoding module. I'm happy to speak with anyone willing to lend a hand; shoot me an email at turfcuttergm@mindlessphilosopher.net .