Gateway to PDF

Okay, here's a quick and dirty index page for my sector-to-PDF Perl script and sample output for QLI's Traveller D20 Gateway to Destiny campaign sourcebook, as discussed here in their forums.

Updated 3/20/2005: minor fix to sec2pdf so it works with the new version of PDF::API2 that's on CPAN. Should still work with the old one, too.

Updated 11/15/2004: updated domain-level map with new one auto-generated from upcoming version of sec2pdf.

Updated 11/14/2004: Added ability to annotate map with text labels (a bit clumsy, but workable), and labeled all of the allegiance borders.

Updated 11/08/2004: Added first public version of allygen, which generates plausible regional borders for a SEC file.

Updated 11/05/2004: Cleaned up default map style file, added command-line option for alternate style files, created commented sample for white-on-black map style. Also fixed map auto-sizing to fill the paper more efficiently.

Updated 11/01/2004: Corrected typos in Glimmerdrift SEC data, added light shading of all systems in Gateway that have official QLI writeups.

Updated 10/31/2004: Fixed filled-region bug, added custom-sized map of Shanape Link Worlds campaign setting.

Updated 10/29/2004: Added --firsthex, --landscape, and --auto options, and updated --type to allow support arbitrary number of columns and rows in a map. See below for details.

Updated 10/28/2004: All maps updated with xboat/trade routes, allegiance borders, and (Spinward Marches only) shaded regions. I've also fixed the -g option to override any colors specified in metadata files, to make sure that the maps are reasonably clear on B&W printers.

Bugs? Suggestions? Comments? Here.

Files

sec2pdf: The Perl script that generated all of these maps (requires PDF::API2 from CPAN).
darkmap.txt: A heavily-commented map style definition file that creates white-on-black maps, for use with the new --style option.
SpinwardMarches.txt: Sample metadata file that lists subsector names, xboat routes, borders, and shaded map regions, based on what we think was the MegaTraveller map of The Spinward Marches. Used to generate the annotated map below.
allygen: Perl script that tries to create plausible regional borders for a sector, based on starports, tech level, and population. More docs later, but here's a short usage sample: "allygen -s Im,IL,IU -n Na,IC -o foo SpinwardMarches.sec" (write border data for Spinward Marches to foo.msec, treating Im, IL, and IU as the same allegiance, and treating Na and IC as non-aligned worlds that are outside all borders). Adding the "-i" option will ignore pre-existing allegiances and generate new ones, writing the results to foo.sec. Adding "-f 1" will increase the area influenced by a starport, and "-f -1" will reduce it. Note that with certain legacy sectors, non-aligned worlds appear to be inside the borders of surrounding large allegiances. This is actually a failure to draw concentric regions correctly, and the workaround is to... not use the -n switch.
SectorData.zip: Complete collection of SEC and metadata files used to create these maps. Includes xboat routes and allegiance borders.
Gateway Domain: All four sectors of Gateway Domain, assembled onto a single page. This map is a lot of fun on-screen, but basically unreadable on any paper you can fit into a standard home or office printer, so the 11x17 paper size was selected just for convenience. Note that this map is now generated entirely within sec2pdf (coming-soon version), so as soon as I clean the code up a bit, it will be possible to generate this sort of map for any four adjacent sectors.
The Shanape Link Worlds Cluster: This is a mini-campaign set in Ley Sector, shipped as part of the Traveller D20 Referee's Screen package. The arguments used to generate this map were: "sec2pdf -d Ley.sec -b -h -t 12x9 -f 0317 -l".
Crucis Margin Sector [zip]: Color 8.5x11: sector, by quadrant, by subsector.
Color 11x17: sector, by quadrant.
B&W 8.5x11: sector, by quadrant, by subsector.
Gateway Sector [zip]: Color 8.5x11: sector, by quadrant, by subsector.
Color 11x17: sector, by quadrant.
B&W 8.5x11: sector, by quadrant, by subsector.
Glimmerdrift Reaches [zip]: Color 8.5x11: sector, by quadrant, by subsector.
Color 11x17: sector, by quadrant.
B&W 8.5x11: sector, by quadrant, by subsector.
Ley Sector [zip]: Color 8.5x11: sector, by quadrant, by subsector.
Color 11x17: sector, by quadrant.
B&W 8.5x11: sector, by quadrant, by subsector.
The Spinward Marches [zip] (based on this archive): Color 8.5x11: sector, by quadrant, by subsector.
Color 11x17: sector, by quadrant.
B&W 8.5x11: sector, by quadrant, by subsector.

Using the sec2pdf script

If you want to generate your own maps, you need Perl. If you're on any reasonably recent Mac, Unix, or Linux box, you should already have it, although it might not be in the same place as on my Mac (/usr/bin). You'll need to download and install the PDF::API2 module, and on most desktop unix-alikes, you can just type "sudo cpan PDF::API2". In places where you don't have the privileges to do this sort of thing, you'll need to chat up your local sysadmin and do a little begging.

For Windows, you need to visit activestate.com and download the latest version of ActivePerl (currently 5.8.4) to install on your machine. Once it's installed, run Perl Package Manager, which opens a terminal window, and type "install PDF::API2". When that's finished, you'll be able to open a fresh cmd window, cd to the directory containing the sec2pdf script and your data files, and run it as "perl sec2pdf [options]".

[Note that the current production version of PDF::API2 is 0.3r77, which is what CPAN and ActiveState's Perl Package Manager installs as of 10/28/2004. It looks like the various alpha versions of 0.40 make some significant changes to the modules, such that my trick for setting up a clipping region in PDF::API2::Lite will no longer work. I'd prefer not to rewrite everything, so if the final release of 0.40 includes this change, I'll have to figure out a workaround]

To-do list

Add proper port symbols.
Add a printed map legend.
Add metadata keywords for printing text in arbitrary locations on the map.

Command-line options

Short version? To make an annotated color map of the Spinward Marches on 11x17 paper, type "perl sec2pdf -abBch -tsector -p11x17 -d SpinwardMarches.sec -o spinward.pdf".

Still with me? Here goes:

--all (-a): Generate entire sector, using multiple pages for quadrant and subsector maps.
--auto (-A): Auto-scale the map based on the data in the SEC file. Does not work with --all.
--border (-b): Print a border around the outside edge of the maps.
--boundaries (-B): Print the subsector boundaries on quadrant and sector maps.
--cleanup (-c): Reduce the clutter on the map by leaving out the labels on empty hexes.
--data file (-d): Name of a SEC-format data file describing the systems in a sector.
--firsthex NNNN (-f): Start the map at NNNN instead of 0101. Does not work with --all. The starting column must be odd (the script will warn you and fix it).
--grayscale (-g): Print the map in grayscale instead of full color, for laser printers and people with color-deficient vision.
--highlight (-h): Highlight high-population worlds with the traditional ALL-CAPS names instead of boldface
--landscape (-l): Rotate the page from portrait (tall) to landscape (wide). Necessary for full use of --auto and --type.
--metadata file (-m): Name of a file containing additional data about the systems in a sector (see SpinwardMarches.txt for an example of the format). If "--data file.sec" has been specified, the script will automatically look for file.msec containing this data.
--output file (-o): Name of a file to write the PDF output into (defaults to grid.pdf).
--paper size (-p): The name of a paper size to scale the maps onto. The complete list of valid sizes is: 4x6, 8.5x11, 8.5x14, 11x17, 18x24, 24x36, 36x48, a0, a1, a2, a3, a4, a5, a6, b0, b1, b2, b3, b4, b5, and b6.
--sector name (-s): The sector name, to be printed as the map title (overrides any value present in the metadata file).
--style file (-S): A file containing map style definitions (see darkmap.txt sample above).
--type sector|quadrant|CxR (-t): The scale of map to print on each page. Sector maps are 32x40, quadrant maps are 16x20, and the default subsector maps are 8x10. You can also directly specify the number of columns and rows on a page as colsxrows. The number of columns must be even (the script will warn you and fix it). It's up to you to specify the --landscape option to fit wide maps onto the page correctly.
--uwpprint (-u): Ignore the system names, and instead print the UWP and PBG values (the normal behavior for systems that don't have names).
[column row]: By default, the script will print the upper-leftmost portion of a sector (the "A" subsector, or the "Alpha" quadrant). If you want to make a single-page PDF file of another portion of the sector, you need to give its column and row. E.g. the "Gamma" quadrant is "1 2", and the "N" subsector is "2 4".

Disclaimer

The Traveller game in all forms is owned by Far Future Enterprises. Copyright 2002 QuikLink Interactive, Inc. Traveller is a registered trademark of Far Future Enterprises. QuikLink permits web sites and fanzines for this game, provided it contains this notice, that QuikLink is notified, and subject to a withdrawal of permission on 90 days notice. The contents of this site are for personal, non-commercial use only. Any use of QuikLink Interactive's product identity, copyrighted material or trademarks anywhere on this web site and its files should not be viewed as a challenge to those copyrights or trademarks. In addition, any program/articles/file on this site cannot be republished or distributed without the consent of the author who contributed it.