sec2pdf: getting started

I often say that I’m not a programmer, I’m a problem-solver who occasionally writes code to eliminate annoyances. One recent annoyance was what passes for “state of the art” in creating star maps for the Traveller RPG.

When we decided to start a D20 Traveller campaign as an alternative to our semi-regular D&D game, one of the many things we had to get up to speed with was the universe itself, represented as a bunch of data tables and hex-grid star maps. Over the decades, a number of efforts have been made to convert this mass of data from dead trees into bits, with varying degrees of success (at the very least here, here, here, here, and of course here).

T20 publisher QLI allows free distribution of the system data and star maps corresponding to their Gateway to Destiny campaign setting, but the book, data files, and PDF maps are not perfect, and in some cases have different errors. Why? Because the process of creating the maps from the data basically consisted of running a script that created a script that created a CAD document that was corrected and annotated by hand, then printed to a PostScript file, and finally converted to a PDF file. I gather the CAD import (Campaign Cartographer, by the way) could take an hour or more, depending on the complexity of the data and the speed of your hardware.


As I said, I’m not a programmer. I have, however, been hacking with Perl and PostScript since the Eighties, and this process was so absurd that I couldn’t not try to fix it. Producing PDF maps directly from the source data seemed like the way to go, and by happy accident I’d recently updated one of my old Perl/PS hacks to use the PDF::API2::Lite CPAN module, so I knew I could do it. It took about an hour to get the first version working, most of a day to nail down the feature set, and another afternoon to clean it up enough to be worth sharing with the world. On my laptop, it takes about ten seconds to produce a fully-annotated sector map, split across one, four, or sixteen pages.

One of the first things that became obvious as I knocked the script together was the correctness and completeness of the source data. It was incorrect, incomplete, poorly formatted, and in many cases poorly transcribed (my favorite: many years ago the Dodds system accidentally became Doods). A lot of the most interesting data about the many “sectors” that had been developed for the game wasn’t captured at all in the most popular (SEC) format, and only partially in the DOS-based Galactic archives. There’s no profit in creating Yet Another Sector Format at the moment, so I settled for creating a simple keyword-value format that captured all of the other data, including the full names of star systems that don’t fit into SEC’s 14-character fixed-length field.

There are still some things on my to-do list for sec2pdf, but I’m generally satisfied with its capabilities right now. I’ve accomplished the primary goal of making maps that look at least as good as the ones being published, with less effort and greater accuracy. There are still some things to add (a map legend, the ability to print arbitrary text anywhere on the map, improved map symbols for different types of bases, and code to merge multiple sectors into a truly large-scale star map), but that’s gravy; the problem is solved.

Along the way, though, a few things came up that I want to talk about some more, in separate articles:

  • The good and bad things about PDF::API2 in general and PDF::API2::Lite in particular.
  • Figuring out not only how to draw "regional borders" along the edges of a set of hexes, but how to describe the process in a way that would make sense to humans.
  • Coming up with a map-layout configuration system that was both simple and flexible, allowing me to avoid the common trap of embedding formatting details in the code.
  • The ideas, implementation details, and fun problems involved in my spinoff project allygen, which analyzes sector data to create a plausible set of regional borders that can be fed into sec2pdf.