Welcome to MsJSON’s documentation!

MsJSON Mapfile serialiser

A package for converting UMN Mapserver mapscript objects to and from JSON for Python 2.x.

Mapscript:

JSON:

Usage

The usage is simple:

# coding: utf-8

import mapscript
import msjson

msobj = mapscript.mapObj('/path/to/mapfile.map')
m = Map(mapscript_=msobj, mapfile_encoding='cp1252')
print m.to_json()

or to convert an object from json.load(s):

json_object = {
    'name' : 'Foo',
    'imagecolor' : {
        'red': 255, 'green': 255, 'blue': 255
    }
}
m = Map()
m.mapfile_encoding = 'cp1252'
m.from_json(json_object)
m.mapscript.save('/path/to/mapfile.map')

You can also set the properties directly:

m = Map()
m.name = 'Foo'
m.imagecolor = {'red': 255, 'green': 255, 'blue': 255}

Just make sure that everything after the equal sign is the jsonable representation of the value. For examples of the JSON representation of an object see their documentation.

Note

Only properties necessary for the configuration are serialised. Mapscript properties like numlayers are skipped. But you can easily add them to your configuration.

The serialisation of almost any mapscript.xyzObj is supported, just pass it as an argument to the appropriate msjson class object. Right now the package lacks support for mapscript.fontSetObj and the outputformat list for the mapscript.mapObj [1]. The currently selected outputformat can be exported though through the use of msjson.OutputFormat.

Note

The JSON of a serialised map file can contain more attributes than defined in the map file. This is due to the nature of mapscript where most properties have default values defined. Some properties, like colors have a value for beeing “not set”. These values are also read and transformed into JSON if being configured on the corresponding msjson object.

So if your map file holds no background image color configuration value, but the backgroundcolor property is defined on the Map it is read from the mapscript.mapObj and transformed into JSON.

This behavior may change in the future!

The logic of the package is based on the descriptor pattern in Python and the style of the configuration is borrowed from database ORM libraries like SQLAlchemy.

Mapscript compatibility between versions

It may happen that properties on mapscript objects are existant in one version but not in another. Mapscript on Debian Squeeze 6 is of version 5.6.6, Mapscript on Ubunut 8.04 is of Version 6.0.0 (from the UbuntuGIS repository). The Debian version features a autoangle property on the labelObj while the Ubuntu version does not.

Debian 6 Squeeze:

>>> import mapscript
>>> hasattr(mapscript.labelObj(), 'autoangle')
True

Ubuntu 8.04 (UbuntuGIS):

>>> import mapscript
>>> hasattr(mapscript.labelObj(), 'autoangle')
False

This may be true for more properties than autoangle. To circumvent problems with properties that do not exist on certain mapscript versions the logic of MsJSON deals flexible with non-existant properties. When you call to_json() and a non-existant property is encounterd on the mapscript object a value of None is bound to the defined property name. Equally when trying to set a value on a non-existant property the action is skipped if the property doesn’t exist. In each case a DeprecationWarning is issued. Depending on your Python version the output of the warning may be suppressed.

Own Jsonifiers

You can create your own Classes for JSON serialisation, there is no need to stick to the predefined classes from the package. Just define your own handlers and you are ready to go:

# coding: utf-8
import mapscript
import msjson
from msjson.base import Base

class MyMap(Base):
    base = mapscript.mapObj

    # json attribute = mapscript attribute
    a_name = msjson.String('name')
    a_color = msjson.Color('imagecolor')
    numlayers = msjson.Integer('numlayers')

m = MyMap()
m.to_json()

Each class derived from Base must have a class property base wich holds a reference to the corresponding mapscript object. Everything else can be configured as needed.

Using classes below Map

For every mapscript.xyzObj exists a represention class in the package wich deals with the conversion from and to JSON. There are different kinds of conversion handlers which deal with different aspects of the mapscript behavior in retrieving and setting values. There are Types, Datatypes, Base classes and Classes.

Types

There are classes, so called types, for the most basic data representations in mapscript. These are:

Since these are mostly values they do not have a direct jsonable representation but return values directly with the exception of msjson.Collection and msjson.Size which return lists.

Datatypes

Datatypes represent mapscripts variables and map directly between Python data types and mapscript variables. Like Types, these also do not have a jsonable representation and return values directly. There are the following classes:

Base classes

Base classes represent a mapscript.xyzObj and may have one or more Types, Datatypes or other Base classes as properties.

Base classes are:

Classes

Classes are the top level representations of mapscript objects. Classes include:

Each class has a collection object which wraps around the number of child elements of each class, i.e. the layers of the mapscript.mapObj object, the classes of the mapscript.layerObj object and the styles of the mapscript.classObj object. There is no direct iteration over child elements of an object in mapscript so the Collection class is used for retrieving, removing and inserting child elements.

Types

Types represent the most basic values. They map strings, numbers and certain mapserver specific types to and from python values.

e.g.:

Map(Base):
    name = String('name')
    res = Float('resolution')
    height = Integer('height')

Property

class msjson.types.Property(property_name=None, mapfile_encoding=None)

Property base class

Implements the Descriptor pattern. This should be the base for new mapscript class properties.

Property.__init__(property_name=None, mapfile_encoding=None)
Parameters:
  • property_name

    Mapscript property name.

    holds the property name of the mapscripts’ object property, e.g. name for mapscript.mapObj . name. This is used in conjunction with getattr and setattr for setting and retrieving values to and from a mapscript object.

  • mapfile_encoding

    Encoding of mapfile.

    holds the encoding name of the mapfile encoding. Gets usually copied from the parent instance. Only the first class defines this and each subclass tries to copy the value from its parent class.

Property.__get__(instance, owner)

__get__ always returns a json representation of the Property

Property.__set__(instance, value)

__set__ sets the property from a json representation of the Property

Decoding

Property.decode(value)

Try to decode a string from mapfile encoding to json encoding. If no mapfile_encoding is defined the value is returned directly. If decoding with mapfile_encoding fails the value from the mapscript object is returned directly.

Encoding

Property.encode(value)

Try to encode a json string from json encoding to mapfile encoding. If no mapfile_encoding is defined the value is returned directly. If encoding with mapfile_encoding fails the value from JSON is returned directly.

Collection

class msjson.types.Collection(base, get, remove, insert, numitems)

Represents a collection of child elements of a mapscript object. The intended use is for layers in a map object, classes in a layer object or styles in a class object.

e.g.:

layers = Collection('getLayer', 'removeLayer', 'insertLayer',
                    'numlayers')

The JSON representation of the collection is a list of jsonified child items.

Collection.__init__(base, get, remove, insert, numitems)
Parameters:
  • base

    Base class for the collection.

    The base class of the collecion is usually any of Layer, Class or Style.

    New instances of base are created while reading the child objects from the descriptor instance and are converted to/from json.

  • get

    Name of the mapscript function for retrieval.

    This is getLayer(), getClass() or getStyle() of the corresponding mapscript object. Pass the name as string().

  • remove

    Name of the mapscript function for removal.

    This is removeLayer(), removeClass() or removeStyle() of the corresponding mapscript object. Pass the name as string().

  • insert

    Name of the mapscript function for inserting.

    This is insertLayer(), insertClass() or insertStyle() of the corresponding mapscript object. Pass the name as string().

  • numitems

    Name of the attribute for the number of items.

    This is numlayer, numclasses or numstyles of the corresponding mapscript object. Pass the name as string().

Expression

class msjson.types.Expression(property_name=None, mapfile_encoding=None)

Class for mapping Mapserver expressions to and from JSON. getExpressionString() and setExpression() are used on mapscript.classObj to retrieve the expression.

e.g.:

CLASS
    EXPRESSION ("[DESCRIPTIO]" == "Naturelle")
END

Float

class msjson.types.Float(property_name=None, mapfile_encoding=None)

Class for mapping float numeric values to and from JSON.

ImageType

class msjson.types.ImageType(property_name=None, mapfile_encoding=None)

Class for retrieving the imagetype from mapObj.

Warning

Setting this is currently not fully functional. Problems arise if the output formats are not set on the mapscript object, but ImageType tries to set one which (yet) does not exist.

e.g.:

MAP
    IMAGETYPE "png32"
END

Integer

class msjson.types.Integer(property_name=None, mapfile_encoding=None)

Class for mapping integer values to and from JSON.

Projection

class msjson.types.Projection(property_name=None, mapfile_encoding=None)

Class for getting and setting the projection string on the mapscript mapscript.mapObj or mapscript.layerObj. Uses getProjection() and setProjection() to retrieve projection information.

e.g.:

MAP
    PROJECTION
        "proj=lcc"
        "lat_1=51.16666723333333"
        "lat_2=49.8333339"
        "lat_0=90"
        "lon_0=4.367486666666666"
        "x_0=150000.013"
        "y_0=5400088.438"
        "ellps=intl"
        "towgs84=-106.869,52.2978,-103.724,0.3366,-0.457,1.8422,-1.2747"
        "units=m"
        "no_defs"
    END
END

Size

class msjson.types.Size(property_name=None, mapfile_encoding=None)

Class for setting and getting the map size in pixels. Uses getSize() and setSize() on the mapscript.mapObj for retrieval of values. The return/set value is a tuple() in the form of (width, height).

e.g.:

MAP
    SIZE 1000 1000
END

String

class msjson.types.String(property_name=None, mapfile_encoding=None)

Class for mapping string values to and from JSON. Uses Decoding and Encoding to read the values from a mapfile correctly and transfer them between the JSON encoding.

Text

class msjson.types.Text(property_name=None, mapfile_encoding=None)

Class for retrieving and setting the text of a classObj. Uses getTextString() and setText() on the mapscript.classObj.

e.g.:

CLASS
    TEXT "N"
END

Datatypes

Datatypes are a handler between mapserver variables and Python data types. In order to provide a consequent API between mapscript and JSON, a dict() is used to map between both.

e.g.:

Map(Base):
    # set a data type
    status = Status('status')

DataType

class msjson.datatypes.DataType(property_name, mapfile_encoding=None)

Represents mapscript variables

see http://mapserver.org/mapscript/variables.html for a complete list of available variables. Uses a mapping dict to transfer between mapscript variable value and python values.

Inherits from Property.

Align

class msjson.datatypes.Align(property_name, mapfile_encoding=None)

Align data type

Maps alignment properties to or from string representation.

Alignments are: - ‘left’ : mapscript.MS_ALIGN_LEFT - ‘center’ : mapscript.MS_ALIGN_CENTER - ‘right’ : mapscript.MS_ALIGN_RIGHT - None : -1

Boolean

class msjson.datatypes.Boolean(property_name, mapfile_encoding=None)

Boolean data type

Maps mapscript.MS_TRUE and mapscript.MS_FALSE values to and from python boolean conditions. Additionally there’s also a “not set” condition, represented by python’s None and -1 for mapscript.

Connection

class msjson.datatypes.Connection(property_name, mapfile_encoding=None)

Connection data type

maps a mapscript connection type to or from a string representation. Mapped connections are:

  • ‘inline’ : mapscript.MS_INLINE
  • ‘shapefile’ : mapscript.MS_SHAPEFILE
  • ‘tiled_shapefile’ : mapscript.MS_TILED_SHAPEFILE
  • ‘sde’ : mapscript.MS_SDE
  • ‘ogr’ : mapscript.MS_OGR
  • ‘postgis’ : mapscript.MS_POSTGIS
  • ‘wms’ : mapscript.MS_WMS
  • ‘oracle’ : mapscript.MS_ORACLESPATIAL
  • ‘wfs’ : mapscript.MS_WFS
  • ‘graticule’ : mapscript.MS_GRATICULE
  • ‘raster’ : mapscript.MS_RASTER

ImageMode

class msjson.datatypes.ImageMode(property_name, mapfile_encoding=None)

ImageMode data type

Mapping:

  • ‘pc256’ : mapscript.MS_IMAGEMODE_PC256
  • ‘rgb’ : mapscript.MS_IMAGEMODE_RGB
  • ‘rgba’ : mapscript.MS_IMAGEMODE_RGBA
  • ‘int16’ : mapscript.MS_IMAGEMODE_INT16
  • ‘float32’ : mapscript.MS_IMAGEMODE_FLOAT32
  • ‘byte’ : mapscript.MS_IMAGEMODE_BYTE
  • ‘null’ : mapscript.MS_IMAGEMODE_NULL

LayerType

class msjson.datatypes.LayerType(property_name, mapfile_encoding=None)
LayerType data type

Mapping:

  • ‘point’ : mapscript.MS_LAYER_POINT
  • ‘line’ : mapscript.MS_LAYER_LINE
  • ‘polygon’ : mapscript.MS_LAYER_POLYGON
  • ‘raster’ : mapscript.MS_LAYER_RASTER
  • ‘annotation’ mapscript.MS_LAYER_ANNOTATION
  • ‘query’ : mapscript.MS_LAYER_QUERY
  • ‘circle’ : mapscript.MS_LAYER_CIRCLE
  • ‘tileindex’ mapscript.MS_LAYER_TILEINDEX

Position

class msjson.datatypes.Position(property_name, mapfile_encoding=None)

Position data type

Mapping:

  • ‘ul’ : mapscript.MS_UL
  • ‘ll’ : mapscript.MS_LL
  • ‘ur’ : mapscript.MS_UR
  • ‘lr’ : mapscript.MS_LR
  • ‘cl’ : mapscript.MS_CL
  • ‘cr’ : mapscript.MS_CR
  • ‘uc’ : mapscript.MS_UC
  • ‘lc’ : mapscript.MS_LC
  • ‘cc’ : mapscript.MS_CC
  • ‘auto’ : mapscript.MS_AUTO
  • None : 111

Status

class msjson.datatypes.Status(property_name, mapfile_encoding=None)

Status data type

Mapping:

  • ‘on’ : mapscript.MS_ON
  • ‘off’ : mapscript.MS_OFF
  • ‘default’ : mapscript.MS_DEFAULT
  • ‘embed’ : mapscript.MS_EMBED

Unit

class msjson.datatypes.Unit(property_name, mapfile_encoding=None)

Unit data type

Mapping:

  • ‘dd’ : mapscript.MS_DD
  • ‘feet’ : mapscript.MS_FEET
  • ‘inch’ : mapscript.MS_INCHES
  • ‘meter’ : mapscript.MS_METERS
  • ‘miles’ : mapscript.MS_MILES
  • ‘nautical’ : mapscript.MS_NAUTICALMILES
  • ‘pixel’ : mapscript.MS_PIXELS

Base Classes

Bases

Holds the most basic mapscript object handlers. Basic in terms of their properties, not their simpleness. The handlers themselves do not have Types or Datatypes properties. They just return or receive JSON objects.

Base

class msjson.base.Base(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

The Base Class for all Mapserver JSON objects

Can either be used as a descriptor on other classes or as a standalone version. Inherits from Property.

Base.__init__(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)
Parameters:
  • property_name

    Mapscript property name.

    holds the property name of the mapscripts’ object property, e.g. name for mapscript.mapObj . name. This is used in conjunction with getattr and setattr for setting and retrieving values to and from a mapscript object.

  • mapscript

    mapscript object

    holds the mapscript object for json serialisation

  • json

    json object

    holds the json object for direct instatiation from a json object.

  • init_param

    mapscript object instantiation parameter

    holds eventually necessary instatiation parameters of mapscript objects. At the moment it is only useful for mapscript.outputFormatObj as this class takes the driver name on instanciation.

  • mapfile_encoding

    Encoding of mapfile.

    holds the encoding name of the mapfile encoding. Gets usually copied from the parent instance. Only the first class defines this and each subclass tries to copy the value from its parent class.

Base.to_json()

Return a jsonified version of self

Base.from_json(json)

Initialise self from a jsonified version

Color

class msjson.base.Color(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A Color object property

Handles mapscript.colorObj objects. The JSON representation of Color is:

{
    'red': [-1, 0-255],
    'green': [-1, 0-255],
    'blue': [-1, 0-255]
}

The values in square brackets indicate possible values, where -1 means not set and 0-255 is the possible value range.

HashTable

class msjson.base.HashTable(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A HashTable object

Handles mapscript.hashTableObj objects. The JSON representation is a flat, not nested dict().

Rect

class msjson.base.Rect(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A rectObj (Extent)

Handles mapscript.rectObj objects. mapscript.rectObj are primarily used on mapscript.mapObj and mapscript.layerObj objects to define the extent. The JSON representation of Rect is:

{
    'minx': [-1, ..],
    'maxx': [-1, ..],
    'miny': [-1, ..],
    'maxy': [-1, ..]
}

The values in square brackets indicate possible values where -1 means not set and .. means any floating point number. Obviously the values for minx and miny should be smaller than the values for maxx and maxy. Otherwise the mapscript object will raise an error.

Base classes

This module contains only classes that do not have other mapscript classes as property but only types, datatypes and base classes. For a full list of properties the mapscript manual can be consulted.

e.g.:

Map(Base):
    legend = Legend('legend')

FontSet

class msjson.baseclasses.FontSet(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A FontSet object

Handles mapscript.fontSetObj objects.

Warning

This is currently broken. Trying to access the mapscript.fontSetObj . fonts property results in a segmentation fault on the mapscript side.

Label

class msjson.baseclasses.Label(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A Label object

Handles mapscript.labelObj objects. A label is usually a property of Class objects.

e.g.:

Class(Base):
    label = Label('label')

Legend

class msjson.baseclasses.Legend(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A Legend object

Handles mapscript.legendObj objects. A legend is usually attached to a Map objects legend attribute.

e.g.:

Map(Base):
    legend = Legend('legend')

OutputFormat

class msjson.baseclasses.OutputFormat(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

An OutputFormat object

Handles mapscript.outputFormatObj objects. An OutputFormat object can be used to obtain the outputformat attribute of the mapscript.mapObj object. And it should be part of the outputformatlist attribute of the mapscript.outputFormatObj object. The manual notes for the outputformatlist:

Note

outputformatlist : outputFormatObj[] Array of the available output formats.

Note: Currently only available for C#. A proper typemaps should be implemented for the other languages.

So obtaining a list of outputformats is currently not possible. While it is possible to obtain the number of outputformats registered for a map there exists no possibility to iterate over the outputformats, there’s only a getter method (getOutputFormatByName()) by name, not by index.

e.g.:

Map(Base):
    output_format = OutputFormat('outputformat')

ScaleBar

class msjson.baseclasses.ScaleBar(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A ScaleBar object

Handles mapscript.scalebarObj objects. A ScaleBar is usually attached to a Map object.

e.g.:

Map(Base):
    scalebar = ScaleBar('scalebar')

Style

class msjson.baseclasses.Style(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A Style object

Handles mapscript.styleObj objects. A Style is part of a collection of Style objects attached to a Class object and is normally not used directly. It can be used to jsonify a mapscript.styleObj object though.

e.g. in a Collection:

Class(Base):
    styles = Collection(Style, 'getStyle', 'removeStyle', 'insertStyle'
                        'numstyles')

or as standalone:

import mapscript
import msjson

ms_style = mapscript.styleObj()
style = msjson.Style(mapscript_=ms_style)
style.to_json()

Web

class msjson.baseclasses.Web(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A Web object

Handles mapscript.webObj objects. A Web object is usually attached to a Map object.

e.g.:

Map(Base):
    web = Web('web')

Classes

This module contains the three most advanced classes for dealing with mapscript.classObj, mapscript.layerObj and mapscript.mapObj objects. All of these have a property of type Collection for dealing with their list like child elements.

e.g.:

Class(Base):
    debug = Integer('debug')
    # ... other properties
    styles = Collection(Style, 'getStyle', 'removeStyle', 'insertStyle',
                        'numstyles'

Class

class msjson.classes.Class(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A Class object

Handles mapscript.classObj objects.

e.g.:

Class(Base):
    debug = Integer('debug')
    # ... other properties
    styles = Collection(Style, 'getStyle', 'removeStyle', 'insertStyle',
                        'numstyles'

Layer

class msjson.classes.Layer(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A Layer object

Handles mapscript.layerObj objects

e.g.:

Layer(Base):
    name = String('name')
    # ... other properties
    classes = Collection(Class, 'getClass', 'removeClass',
                         'insertClass', 'numclasses')

Map

class msjson.classes.Map(property_name=None, mapscript_=None, json=None, init_param=None, mapfile_encoding=None)

A Map object

Handles mapscript.mapObj objects. This is the top level object in the mapscript hierarchy.

e.g.:

Map(Base):
    name = String('name')
    # ... other properties
    layers = Collection(Layer, 'getLayer', 'removeLayer',
                        'insertLayer', 'numlayers')

Footnotes

[1]

outputformatlist : outputFormatObj[] Array of the available output formats.

Currently only available for C#. A proper typemaps should be implemented for the other languages.

Contents:

Indices and tables