Magellan -- Manual ================== Concepts ======== Magellan draws (global-scale) geographical data in a variety of forms and projections. The main concepts used in configuring magellan are: output, orbit, content, projection, viewport, and display. Briefly, these are: output The method of display -- typically writing to a bitmap, or to the X desktop. orbit Specifies a view on the world -- may be time-dependent content Specifies a dataset to be rendered -- a map, outline, lat/long lines, etc. projection The projection to use to render spherical data onto the output. viewport A rectangular region on the output device into which data can be rendered. display Combines a viewport, a projection, a set of content, and an orbit, to render into the output. Each of these concepts and the method of configuring it is described in the following sections. Config file =========== The configuration file consists of a sequence of sections. Each section has a keyword, which is followed by a name enclosed in double quotes for most sections, and then the section data enclosed in braces { }. Configuration directives within a section are a keyword followed by parameters, terminated by a semicolon. The first keyword in every section must be "type" (except display sections). Keywords are case-sensitive, and typically all lower-case. Comments are introduced with // as a comment to the end of the line, or /* */ surrounding a multi-line comment. For example, the following is a short section of a configuration file: /* Fixed-position orbit */ orbit "fixed1" { type fixed-position; // Specify the type position 15.0 20.0; // Hover over North Africa } In the following sections, required directives have no annotation. Optional directives which take parameters are shown with the default values if they are omitted. Optional directives which are simply flags are shown as "Optional". Output section -------------- There can be precisely one "output" section in a configuration file. The output section specifies a rendering method -- how the output is sent to the screen or a file. The "output" section is unnamed. Available output plugins and their parameters are: output { type X-root; update-time ; // Optional } Renders output to the X root window, at -second intervals. Orbit sections -------------- An "orbit" section specifies a viewpoint on the world. This will usually specify a point on the surface of the globe, which will typically be mapped to the centre of any map projection. "orbit" sections must be named. Available orbit plugins are: orbit "" { type fixed-position; position ; // Default: 0 0 } Sit above a fixed point on the globe, at the given longitude and latitude (specified in degrees). orbit "" { type random-position; } Pick a different position at random each time the display is redrawn. If a random-position orbit is used, it will return the same lat/long position for each time the output device is rendered (so displays sharing the same random-position orbit will be centred on the same point). orbit "" { type circular; period ; // Default: 3600 (one hour) time-origin ; // Default: now angle ; // Default: 0.0 nodes ; // Default: 0.0 precession

; // Default: 0.0 upright; // Optional } Run in a circular orbit around the globe, angled over. The orbit takes seconds to complete, and starts at a notional "origin" point at . may be a number, representing seconds before or after the current time, or the special keyword "now" (equivalent to a parameter value of +0). The orbit is angled at degrees from the equator of the globe, and crosses the equator at longitude degrees. The crossing point moves around

degrees for each orbit. If "upright" is specified, then north will always be towards the "top" of the orbit view, otherwise the view will be tilted perpendicular to the plane of the orbit. orbit "" { type sunpos; } View the globe from the point at which the sun is at zenith, for the current date/time. NOTE: This plugin is not currently astronomically accurate, but gives a "good enough" value for display purposes. This behaviour is considered a bug. ref { ref ""; } Where an orbit is needed, refer to an alternative named orbit section. This can be used where identical orbits are needed in more than one place. Content sections ---------------- A "content" section specifies a collection of content which can be used together. Within a content section are one or more subsections, giving a type of data, and parameters for that data. Content sections must be named. Available content plugins are: bitmap { file ""; smooth; // Optional } Renders a bitmap wrapped around the globe. The bitmap should be twice as wide as it is tall. If magellan was compiled with paintlib, then most common bitmap formats are supported. If compiled with libjpeg, then only JPEG format files are supported. The optional keyword "smooth" specifies whether to try smoothing the bitmap data as it is rendered. Files are searched for in the following directories: * /usr/lib/magellan/bitmap * /usr/local/lib/magellan/bitmap * ~/lib/magellan/bitmap * Directories specified with the --include= option on the command line latlongmarks { longitude-divs ; // Default: 0 or *2 longitude-minor-divs ; // Default: 1 or latitude-divs ; // Default: 0 or /2 latitude-minor-divs ; // Default: 1 or colour ; // Default: 255 255 255 (white) scale-long-divs; // Optional } Renders a latitude/longitude grid. The grid has major longitudinal divisions around the 360 degrees of the equator, and major latitudinal divisions along the 180 degrees from pole to pole. Each set of divisions is made of or points. If scale-long-divs is set, then the number of minor divisions on longitudinal lines will be scaled according to the latitude, to ensure approximately equal separation of the points on the globe. check { longitude-divs ; // Default: 2 latitude-divs ; // Default: /2 colour1 ; // Default: 255 255 255 (white) colour2 ; // Default: 255 0 0 (red) } Renders a checked pattern of alternating "squares" along lines of latitude and longitude. The longitude-divs and latitude-divs work the same as the corresponding parameters in a "latlongmarks" section (see above). terminator { sun { (orbit parameters) } day { (content) } night { (content) } boundary-width 5.0; boundary-blend ; } Renders either the day content, or the night content, depending on the position of the sun (defined by the notional "orbit" in the "sun" section). If boundary-width is specified and larger than zero, it indicates the width of the terminator on the day side of the notional terminator line, in degrees. The boundary-blend option indicates what kind of blending between the two sides is used. Values are "linear", "quadratic" or "normal". With "boundary-blend normal", the boundary-width is ignored, and shading based on a simple normal vector is used instead. loxodrome { start ; end ; loops ; colour ; } Renders a line of constant heading from the start position to the end position. If loops is more than one, additional loops around the globe (in the direction of increasing longitude) are added. Currently plots precisely 100 dots on the line. ref { ref ""; } References and includes a named content section. Use of ref sections will reduce the memory footprint of the application. For example, using two identical bitmap content sections will load two copies of the bitmap. Defining one, and using references will ensure that only one copy is loaded. outline { file ""; filled; // Optional } Renders a set of outlines contained in the given file. If "filled" is specified, the outline is rendered filled. The format of the file is: ,, , , ... , ,, ... Values for coordinates may be floating-point. RGB values are between 0 and 255 each. The value specifies the rendering order of the outlines. Lower values may be obscured by higher values, if they overlap. Outlines should not be self-intersecting. Files are searched for in the following directories: * /usr/lib/magellan/outline * /usr/local/lib/magellan/outline * ~/lib/magellan/outline * Directories specified with the --include= option on the command line Projection sections ------------------- A "projection" section defines a map projection -- the way in which data is transformed from the surface of the globe onto the flat rendering plane of the output. The possible projections are: projection "" { type planar; subtype orthographic; } Performs an orthographic projection -- parallel projection rays from the globe to a plane at right-angles to the projection rays. projection "" { type cylindrical; subtype orthographic; standard-parallels ; // Default: 0 } Performs a cylindrical orthographic projection -- projection rays perpendicular to the north-south axis, projecting onto a cylinder wrapped around the globe. The "standard-parallels" parameter sets the latitudes which are at the correct scale, and should be between 0 and 90 degrees. projection "" { type planar; subtype equal-area; limit ; // Default: 180 } Performs a planar equal-area projection. This projection preserves bearings from the centre point, and preserves area. Thus it becomes extremely distorted towards the edge of the projection. The parameter specifies the angular distance at which the edge of the projection is made, and should be between 0 and 180 degrees. Subtypes lambert and lambert-equal-area are synonyms for this projection. projection "" { type planar; subtype equidistant; limit ; // Default: 180 } Performs a planar equidistant projection. This projection preserves bearings and distance from the centre point. The parameter can be used to cut off the projection at a given distance from the centre. projection "" { type planar; subtype point-projected; projection-centre ; // Default: 0 } Projects radially onto a plane tangent to the globe, from a point at radii from the centre of the globe. projection "" { type planar; subtype stereographic; } A synonym for a planar point-projected projection with projection-centre of 1.0. Preserves bearing from the centre. projection "" { type planar; subtype gnomonic; } A synonym for a planar point-projected projection with projection-centre of 0.0 (i.e. the centre of the globe). Preserves bearing from the centre and great circles become straight lines. projection "" { type mercator; } A Mercator projection. No other options are defined. Viewport sections ----------------- A viewport specifies a rectangular area and scaling factor. It is used to convert a projected set of content into the output area. Map projections are typically two units across (-1 to +1 each way). A viewport can be used to scale and clip a projection. A viewport is defined as follows: viewport "" { bottom-left ; // Default: - - top-right ; // Default: + + size ; // Default: - - scale ; // Default: 1.0 centre ; // Default: /2 /2 } Display sections ---------------- Each "display" section connects a set of content, an orbit, a projection and a viewport. This combination will be rendered into the output. display { viewport ""; orbit ""; content ""; projection ""; } Command line invocation ======================= $ magellan [options] Options are: -c --config= Use the specified configuration file instead of ~/.magellanrc -P --plugin-path= Add the given path to the search path for plugins. -I --include= Add the given path to the search path for data. -D --debug= Print debugging information. is a string consisting of one or more of: p Debug plugin loader c Debug config file parser r Debug rendering engine Letters may be repeated for more debugging information.