Plotter

Plotter is the thing that makes Starmapper fly. Plotter is the thing that makes Starmapper pretty. Plotter is the thing that makes Starmapper useful.
Plotter is king!

Uh, sorry about that.

Description

Plotter∞ is a pluggable object that converts raw numbers generated by Starmapper into pixels. Its mode of operation is simple: initialize a new image -> process lots of pixels -> additional post-processing pass -> return the image. In the meantime it is asked to print some strings∞ and draw some icons∞ (to mark locations of nodes). Basically, Plotter takes care of the actual image that will be returned to the user.

Plotter is given an array of floats (along with the coordinates of the pixel currently processed). Each elements is a value of influence of a region on this point (the actual function used to calculate influences is described FIXME uh, somewhere else... but basically it's proportional to the inverse of the distance). Plotter should know which index describes which region, because upon initialization, Plotter is also given a List of Regions (along with their colours), whose elements are in exactly the same order as in the array of influences.

So, the Plotter can do lots of different things with the data, and so do the many implementations in package jezuch.utils.starmapper3.plotters∞.

Included implementations

• DefaultPlotter∞: default and the most boring one. It finds the Region with maximum influence and paints the pixel with its colour. This is the only Plotter that returns images with indexed color model.
• CappedPlotter∞: a simple extension of the DefaultPlotter. The pixel still has the colour of Region with the maximum influence, but the colour's intensity is proportional to the influence. Of course, the influence value can be unbounded, but the intensity can't, so there's a cap value at which the intensity reaches maximum (it is configurable in the constructor, but by default it's 10.0f).
• SmoothPlotter∞: it's much like CappedPlotter, but the dependence between influence and intensity is non-linear (it's logrithmic). This still needs a cap value (the influence can be very high very near to nodes), but it can be much lower (by default it's 5.0f).
• MixingPlotter∞: this time it's not about maximum - the pixel's color is a mix of all colours of Regions that have an influence on this pixel. All components are calculated as a weighted average - the weights are the influences normalized so that the sum of weights gives 1. This produces really cool images on maps where nodes are dense, but looks flat like DefaultPlotter for sparse maps.
• CappedMixingPlotter∞: it's a mix of MixingPlotter and CappedPlotter. The colours are mixed and then scaled proportional to the sum of influences (capped at 10.0f by default).
• SmoothMixingPlotter∞: it's a mix of MixingPlotter and SmoothPlotter. The colours are mixed and then scaled proportional to logarithm of the sum of influences (capped at 6.66f by default).
• DominationPlotter∞: this one is like DefaultPlotter, but is more strict about what it considers "maximum influence". The colour of the pixel is still the colour of the Region with maximum influence, but this time this influence must be greater than all other influences combined - it has to literally "dominate". This usually generates black stripes between regions (unless there are only two of them).
• BorderPlotter∞ (still somewhat experimental): this is the only one that requires knowledge of more than one pixel at a time to work correctly. It tries to detect borders between regions (like one competing mapper, XTreme Borders for Stars!) by proceeding like DefaultPlotter most of the time but doing a final post-processing pass when all of the pixels are known (the thickness defaults to 4 pixels). This was the motivation for adding this extra pass to the Plotter API, actually (along with additional events and modifications to the app-cli). But note that border detection is currently slower than the calculation of influences :)
• AbstractPlotter: as the name says, it's not a Plotter ready to use, but a convenient base class for other Plotters.

To use a specific Plotter implementation you need to set the global.plotter setting (see the Unified Configuration Model). Some Plotter implementations (look for those near the word "default") can also define their own settings, under the plotter hierarchy (like plotter.capped.cap).