Greetings

Welcome to home page of Starmapper, the mapping utility for Stars! and beyond!

Overview

Starmapper is a mapping utility written in Java. It means that it will read some files and output an image (or series of images) presenting a map of influences of regions (usually colored blobs). It's rather limited in what it can do, but I think it is useful anyway :)

Actually (in version 3) Starmapper consists of several parts:

• starmapper-core: a class/interface library; it performs lots of CPU-heavy calculations given so-called reports and returns a BufferedImage. This can be a one-time operation or a batch. Batch mode means that you give it a bunch of reports to read from and in return you get a BlockingQueue that will be populated with results over time;
• starmapper-app-cli: a traditional CLI application;
• starmapper-app-gui: an additional GUI application for non-geeks [actually it's "traditional" too, in a sense that it was available since Starmapper version 1, but it has always been a second-class citizen ;)];
• jezuch-utils: a library of support classes that are generic (pun intended, for those that get the joke) enough to put them in a library separate from Starmapper.

At some point in time I also created a servlet that sat on a server and generated images from files submitted via HTTP POST. I may revive this subproject some day...

Concepts

Starmapper (the library part) operates on several concepts:

• The Map™: a two-dimensional region. "Two-dimensional" means that every point can be reached by giving two coordinates; currently the coordinates are integer numbers (so the precision is limited, but sufficient for all uses known to me - if you need more, gotta ping me). Important component of The Map is The Space. It is uniformly flat - so forget about mapping a reachability of electromagnetic waves in a complex terrain (sorry);
• Nodes: points on the The Map. They are the basic "skeleton" on which Starmapper operates. They have some properties - like position and name - and can belong to at most one region, called (surprise!) "owner" (can also be owned by noone);
• Regions: these are virtual beings that reside on nodes and can "reach" through space to claim "ownership" of it. Each node can have at most one owning region; it is then determined what "influence" this node has on the surrounding space. The result is a field (as in physics) of influences for each region on the map. At the end, a thing called Plotter takes the calculated influences for each point for each region and creates a pretty picture.
• Node Infos: basically a set of data describing a node at a point in time. Time is specified in unspecified units (which makes some awkward wording in the code - it's just "time" everywhere), dependent on Data Model. Data about a node can contain anything is necessary to calculate its influence, but Starmapper is interested only in the result, including the influence, who is the owner and who says these things about the node (that is the reporter);
• Reports: report is simply a collection of Node Infos from one point in time, although each Node Info can claim being from different time (although not from the future, relative to the report, of course...). There can be more reports from the same time, provided that they have different reporters (reporter is one of the regions on The Map). Every Node Info in a report has an age (how fresh it is), which is the difference between time claimed by the Node Info and the Report's time. In case of conflicts between Node Infos in two reports about the same node, report age becomes important as the final report (taken by Starmapper) can't have multiple sets of information about each node - they have to be merged. Merging is a responsibility of Data Model (see below);
• Data Model: since version 3, nodes, regions and node infos are all actually Java interfaces - this makes Starmapper somewhat generic tool, and the outside world needs to provide concrete implementations of these interfaces. Starmapper bundle contains a default set of implementations that represent galaxies in Stars! game [that's how Starmapper started - I used to be a Stars! junkie] and recently also there's a Data Model for Thousand Parsec;
• Unified Configuration Model: this buzzword-sounding name means a system of passing somewhat type-safe parameters to Starmapper. The same infrastructure can be used by client applications, of course, and that's why it's called "unified".

Historical Note

Previous versions of Starmapper carried the "Stars! mapping utility" moniker. That's a reflection of how it all started - for a couple of years of "best years in my life" i was a Stars! junkie. Stars! is (was?) a turn-based strategy game in which up to 16 players turn into Galactic Imperators and try to destroy each other with their fleets of spaceships. Oh, the memories! Stars! can dump several statistics for the current turn (each turn is one game-year). Several useful tools can take these reports and do lots of interesting things with it. I, for one, wanted to have maps of the Empires. There were at least two tools for that purpose: starmap (very old, written in Pascal) and Xtreme Borders (Visual Basic, yuk! - but very competent tool). I am a geek and wanted to do better. So I wrote Starmapper (version 1). Technically, it was a success. Unfortunately I am the shy kind of geek, so it was a disaster in terms of marketing - almost nobody cared ;) Anyway, that's why in versions 1 and 2 Nodes are called Planets, Regions are Players and Node Infos, are (surprise!) Planet Infos.

I abandoned Stars! a while ago (I still love this game, but don't ask why I left), and Starmapper became my toy project for testing new things. So here is version 3 - Starmapper filtered through second-system effect. It has been generified (quite heavily) to possibly support more data models (by applying a concept of programming to interfaces), so it is no longer tied to reports generated by Stars!. Additionally some restrictions were relaxed - like number of regions [no longer] limited to 16.