API Documentation

I created a page to keep the API documentation in one canonical place:

http://www.travellermap.com/api.htm Ω

Bug Fix: Searching

Minor fix here for an issue I noticed myself - if your search results included a sector, when you clicked it wouldn't be centered or scaled reasonably. A little digging found that when I switched from XML to JSON search result processing I'd dropped some of the logic. Clicking the search results now behaves as it did previously.

I also noticed that I wasn't "stemming" words at all, so I threw in a simple rule to drop 's when indexing - try searching on "trin" and you should get 3 results. Ω

We're out of beta - we're releasing on time!

I'm calling the credits experiment done, and out of beta. Shipped!

You'll now see metadata in the page footer for the area on which the map is centered - including world data if you're over an occupied parsec. The data shown will include:

• Sector Name
• World Hex
• World Name
• World UWP
• Sector Era
• Author
• Source
• Publisher
• Hyperlink to source of data
  

Although not present in the beta, I've added in the Era ("circa 1117") if this is known for the particular dataset - corrections welcome!

Another feature that was in beta was a map legend, a new link in the lower left. This launches a popup window (your browser might block it) which uses the current map style to explain the details. (Question: with J-6 and unlimited fuel, how long would it take to get from Regina to Tertius?)

Also, I've added an experimental new API: /SEC.aspx?sector=SECTORNAME - this dumps a standard SEC file for the specified sector. The column widths are undefined - you'll want to use a regular expression to parse it.

Finally, per request on COTI, you will now see UWPs when zoomed in to 128 pixels/parsec. Ω

Custom Posters

I've added HTTP POST support to the Poster API - including documentation and sample forms.

In English:

If you have a .SEC file you can now upload it and have it rendered for you, including optional XML metadata. However, the sample form is raw - you can't specify rendering options. It should be possible for someone to write a form that exposes all of the rendering options/scale parameters as check-boxes. Ω

Map API Updates

A bunch of internal cleanup and refactoring, which will hopefully have no noticeable impact on the site, and three subtle changes to the Poster API:

• Extra-sector worlds no longer rendered - borders and routes will be shown, but the worlds themselves will not be.
• Added an optional subsector=X argument where X is the A...P index of the subsector. If specified, only that subsector is rendered.
• If no render options are specified, by default a sector poster elides the sector grid lines and a subsector poster elides the subsector grid lines as well.

This should make it easier to use the site as an API for static navigation. For example, the following image is embedded in the blog via the following markup:

<img src="http://www.travellermap.com/Poster.aspx?sector=Spinward+Marches&subsector=C&options=2928&scale=64" border="4" />



The API documentation in the last post was incomplete, so here's another shot:

/Coordinates.aspx?sector=SECTORNAME[&hex=XXYY]

• Maps a sector name (and optional hex coordinate) into sector/hex coordinates
• Results are in XML, or JSON if Accept: application/json is specified
  
• example

/Credits.aspx?x=XCOORD&y=YCOORD

• Looks up the data and credits for a given location, including UWP if available
• Coordinates are in tile-space coordinates (optimized for tile rendering, not navigation); conversion functions are in the script
• Results are in XML, or JSON if Accept: application/json is specified
• example

/MSEC.aspx?sector=SECTORNAME

• Generate a plain tes.MSEC file for use with the sec2pdf utilities
• example

/Poster.aspx?sector=SECTORNAME[&scale=N][&subsector=X][&options=O]

• Generate a GIF or JPEG image of the specified sector (or just subsector). Scale (pixels/parsec) and options can be included
• Image format depends on selected options ("Candy" produces JPEG, otherwise GIF)
• Options are defined in the script
  
• example
  

/Search.aspx?q=QUERY

• Perform a free-text search of names for matching sectors, subsectors and worlds
  
• Results are in XML, or JSON if Accept: application/json is specified
• example

/Tile.aspx?x=XCOORD&y=YCOORD&scale=N&options=O[&w=WIDTH&h=HEIGHT]

• Generate a GIF or JPEG image of the specified region.
  
• Coordinates are in tile-space coordinates (optimized for tile rendering, not navigation); conversion functions are in the script
  
• Image format depends on selected options ("Candy" produces JPEG, otherwise GIF)
• Options are defined in the script
• example
  

In case it isn't obvious, the map page itself works by calling these APIs from JavaScript (primarily Tile, but also Coordinates and Search depending on user actions; use of Credits is still "in beta")

Please feel free to make use of any of these APIs. If you encounter any issues with them, let me know! Ω

Nothing to see here (almost)

Well, hopefully no changes. I've done some behind the scenes tweaks recently though:

• Can now parse other data file formats. This is in anticipation of new data files for T5. Not used yet.
• The web services now provide either XML or JSON data, depending on the HTTP "Accept" header (specify "application/json" to get JSON data, default is still XML). For the curious, the services are:
• /Coordinates.aspx?sector=SECTORNAME[&hex=XXYY] example
  
• /Credits.aspx?x=XCOORD&y=YCOORD (in internal map coordinates) example
  
• /Search.aspx?q=QUERY example
  
• The Beta Page now uses JSON instead of XML for smaller queries and faster parsing
  
• The Beta Page no has switched from using XML/XSLT to JSON/JSONT and should now work in Safari 1.3 (e.g. MacOS X 10.4)

I've also cleaned up a few label positions around the edges of the Imperium, but nothing special. Ω

Metadata and Legend

Updates to "beta" version of the page that includes data and credits for location the map is centered on:

• Click on Control box just inside the border to hide it
• Tweak the formatting of metadata
• Added a link to a Map Legend - feedback appreciated!

Other fixes:

• Fix location of Lesser Rift label
• Tweak UWP parser regex to catch travel zones w/ no base or codes - Clan (1103 Spinward Marches) wasn't showing as an Amber Zone
• Added subsector names for: Provence, Windhorn, Meshan, Astron, Fulani, Theta Borealis, Theron, Iphigenaia, Touchstone, Delphi, Karleaya, Alpha Crucis, Spica, Uistilrao, Aldebaran, Neworld, Banners, Hanstone, Malorn, Hadji, Storr
• Labels now render on top of routes (doesn't obscure the text)
• Precise borders are now shown at scale 4 and higher (i.e. as soon as you zoom in)
• Borders are now thicker at maximum zoom

[Update, January 2008]

The "beta" version of the page mentioned here is out of beta. Ω

Recent Feedback Feedback

Candy looks great, but can you get more images so they don't repeat?

Sure, you render them and I'll include them. 120px x 120px, 24-bit PNGs with 8-bit alpha. Let me know what UWP ranges they should represent.

Can you add a secret parameter to make the candy-style images have higher image quality?

I'll try. I tried making them PNGs to get really crisp results but the compression blew out the memory available for the server process.

Can you make a version I can take with me?

Alas no. Actually crafting a local version isn't that hard, but the overhead of maintaining a desktop application is not something I'm willing to take on. I've shipped widely used desktop applications professionally for many years, and it's not trivial to get something that's decent quality. I took on the web site because it was easy!

Can you add a key? I like Traveller, but I don't know what all of these symbols mean!

Urk, I can't believe I didn't do that. It's on my To Do list. For now, though, here's the cheat sheet.

• The circles in the middle represent the "mainworld" of a system (most important). White = no easily available water present (all in ice caps, desert world, etc), blue = liquid water present (easy refuelling), 4 diamonds = asteroids (it's the easiest thing to draw)
• Small white circle in the upper right indicates a Gas Giant in the system, for fuel skimming
• Symbols in the upper left and lower left indicate bases. Triangles are scout bases; red are scout way stations. Stars are naval bases. (I don't think I render non-Imperial bases at all correctly at the moment.)
• Letters at the top indicate starport class - A = Best, E = Worst, X = nothing
• A circle around the system indicates the travel code; yellow = amber zone (Danger!), red = red zone (Interdicted by the Navy)
• Two letter code in the lower right indicates allegiance (Cs = client state of the Imperium, Zh = Zhodani, So = Solomani, etc)
• Capitalized world names indicate a population >= 1 billion
• Red world names indicate a local capital

Ω

Browser Compatibility Changes

Testing in Apple's new Safari 3 Beta for Windows*, I found some issues with the map. They turned out to be caused by some layout hacks I had in the page code to handle the dynamic layout of the page.

The page is composed of resizing (map) and docked (controls, footer) boxes containing other resizing elements (label controls, search results). Ideally, each element should be sized by the content - i.e. the area taken up by the footer is defined by the size of the elements in the footer, and so on. The page did that using old-school HTML <table> elements, but had some issues I'm still not sure of. (Short version: a relatively sized div set to overflow: scroll, inside a relatively sized table cell makes the cell expand if the content overflows, even if the cell and div size correctly with non-overflowing content.) To overcome the issues I had to have some script that would fix the sizes of some elements when the page size changed. These hacks - often browser specific - worked in IE6, IE7, Firefox 1.5 and Firefox 2.0, Opera 9, and Safari 2. But they caused Safari 3 to stop performing layout correctly - everything looked great, but you couldn't drag the map!

So... not wanting to layer on further hacks I redid the page entirely using modern CSS, and the end results were beautiful. Worked like a charm with IE7, Firefox 1.5 and 2.0, Opera 9 and Safari 2 and 3. Unfortunately, they didn't work in IE6. After much teeth gnashing I found a workaround. (Short version: even in standards compliance mode IE6 can't correctly size elements having top and bottom or left and right defined; however, you can use CSS expressions to compute the width or height.)

(Aside: when CSS was young and fresh, Microsoft took the interpretation of "width includes margins, borders and padding" whereas everyone else took the interpretation of "width excludes margins, borders and padding", and it was the latter which eventually became codified in the CSS standards. You can tell that Microsoft was in the "web developer" mindset rather than the "web designer" mindset. When you are designing for the look of content, you want to frame items (text, images, etc) so the exclusive width makes sense. However, when you are developing a UI, you often compose and nest relatively sized boxes. The CSS notion of "width: 100%" when nesting items is absolutely useless when combined with exclusive margins, padding or border, since the element will end up offset and overlapping its parent's right edge!)

Anyway, the map it all appears to work now... but it's probably broken in some obscure browser. If the map suddenly broke for you (boxes everywhere! oh the huge manatee!) I have the retro version available here: http://www.travellermap.com/index_classic.htm - I'll try to keep it working, but I might break it by accident with future changes to underlying shared components such as styles or code. And please let me know what platform and browser you're using - I might be able to bludgeon the page into shape.

* Safari for Windows is a subtle but effective ploy by Apple to encourage Windows-using web developers who haven't shelled out for a Macintosh to do more testing on their platform. Worked for me!

[Update: January 2008]
Given that the old version works in browsers as old as IE5 and no-one has screamed and complained, the "classic" version of the page is no longer available.
Ω

Candy! Candy! Candy!

Based on some artwork by Wayne Peters (and used with permission), I've done an "eye candy" style treatment for my map site (to augment the colors-on-black style of the Spinward Marches poster and the black-on-white style of the Atlas and LBBs). Pick "Candy" in the drop-down in the upper right.

Check out the area around Regina.

It looks best when zoomed in to 128 pixels/parsec, and looks horrible when
zoomed out significantly.

And now that the rifts are much more visible in the "Candy" style (they used to only be drawn as voids in the fake stars visible when zoomed out). I've also updated the rift boundaries to correspond to star densities rather than the macro-scale borders. They match the micro-scale borders, and so look much better when zoomed in. I've also added the rift near Zhdant and details on the Lesser Rift taken from the Third Imperium fanzine's Map of Charted Space Insert.

Enjoy, and feedback welcome. Ω

Routes for Dagudashaag

Based on the excellent Traveller fanzine Signal-GK, I've added routes for Dagudashaag.

The routes are based on the sector xboat route maps printed in Issue #1. One of the routes shown there are missing from the subsector map in #4 (1409-1709), but the route is logical so I left it in.

Hats off to Leighton Piper for the reprinting work, Andrew Pickford for the original subsector map work and the rest of the Dagudashaag Development Team: J.Duncan Law-Green, Adie Stuart, Stuart Machin, Jae Campbell and Alison Nash.

I tweaked inter-sector routes into Vland and Core to join things up. I'm still not happy with the mess in Laraa near Reference (Core 0140) but I guess I need to wait for the rest of the reprints.

PS: Where's Telura Subsector, in issue #7 according to the Traveller Bibliography? Ω

Metadata/Credits Preview and other Minor Updates

I've updated the code behind the site (both the server side and the client side). There aren't any dramatic changes noticeable by users, but there might be bugs - so let me know!

New stuff:

• You can now specify ?sector=name&hex=xxyy, for example: http://www.travellermap.com/?sector=Verge&hex=2612 - the page will automagically navigate for you, if it can find the sector. You can leave out the &hex=xxyy part too.
• MSEC.aspx and Poster.aspx now return an HTTP 404 error if they can't find the target sector, instead of defaulting to Spinward Marches
• Ran jslint.com over the client side scripts, and did some cleanup.
• Added preliminary sector data and metadata for Kaa G!'kul/Numbis based on work by Mike McKeown
• Created routes, cleaned up borders for Verge
  
• Trojan Reach, Riftspan Reaches and Ealiyasiyw borders cleaned up a bit
• Canopus subsectors added
  

The big pending change can be seen in-progress here:

http://www.travellermap.com/index_creditstest.htm

As you scroll/zoom the map, world data and sector metadata (author, source, URL, etc) will be shown at the bottom of the page. The metadata isn't formatted in a particularly attractive way at the moment, nor is it complete, but this is the direction I'm planning to take with metadata. I may overlay the data on the map itself (lower right corner) rather than having it outside the frame - I'm not sure Ω

Not forgotten!

I'm taking a break from work on the site. I've been working on a few unrelated hobby projects and generally just relaxing.

The site is not abandoned! On deck for future updates are:

• Kaa G!'kul sector recreation by Michael McKeown
• Finer rendering style control, such as hex (instead of boxes) at lower scales
• Credits visible on hover
• System data (UWP, etc) data visible on hover
• Different settings/milieus - including Judge's Guild retro versions of the Gateway Domain, Paranoia Press retro versions of The Beyond and Vanguard Reaches
• Use of precise/generated borders at lower scales

But don't hold your breath - it's probably a few months before the next update. Ω