From 2c83877108c8c045f2039cfbd3915230128b935b Mon Sep 17 00:00:00 2001 From: Dane Springmeyer Date: Mon, 17 Nov 2008 23:44:50 +0000 Subject: [PATCH] Added python docstrings to mapnik Map class --- bindings/python/mapnik_map.cpp | 279 ++++++++++++++++++++++++++++----- 1 file changed, 242 insertions(+), 37 deletions(-) diff --git a/bindings/python/mapnik_map.cpp b/bindings/python/mapnik_map.cpp index eef527083..5f38d32dd 100644 --- a/bindings/python/mapnik_map.cpp +++ b/bindings/python/mapnik_map.cpp @@ -85,41 +85,246 @@ std::vector const& (Map::*layers_const)() const = &Map::layers; void export_map() { - using namespace boost::python; - python_optional (); - class_ >("Layers") - .def(vector_indexing_suite >()) - ; - - class_("Map","The map object.",init >()) - .add_property("width",&Map::getWidth, &Map::setWidth, "The width of the map.") - .add_property("height",&Map::getHeight, &Map::setHeight, "The height of the map.") - .add_property("srs",make_function(&Map::srs,return_value_policy()), - &Map::set_srs,"Spatial reference in proj4 format e.g. \"+proj=latlong +datum=WGS84\"") - .add_property("buffer_size", &Map::buffer_size,&Map::set_buffer_size,"The size of buffer around map in pixels") - .add_property("background",make_function - (&Map::background,return_value_policy()), - &Map::set_background, "The background color of the map.") - .def("envelope",make_function(&Map::getCurrentExtent, - return_value_policy()), - "The current extent of the map") - .def("scale", &Map::scale) - .def("zoom_all",&Map::zoom_all, - "Set the geographical extent of the map " - "to the combined extents of all active layers") - .def("zoom_to_box",&Map::zoomToBox, "Set the geographical extent of the map.") - .def("pan",&Map::pan) - .def("zoom",&Map::zoom) - .def("zoom_all",&Map::zoom_all) - .def("pan_and_zoom",&Map::pan_and_zoom) - .def("append_style",&Map::insert_style) - .def("remove_style",&Map::remove_style) - .def("query_point",&Map::query_point) - .def("query_map_point",&Map::query_map_point) - .add_property("layers",make_function - (layers_nonconst,return_value_policy()), - "Get the list of layers in this map.") - .def("find_style",&Map::find_style,return_value_policy()) - .def_pickle(map_pickle_suite()) - ; + using namespace boost::python; + python_optional (); + class_ >("Layers") + .def(vector_indexing_suite >()) + ; + + class_("Map","The map object.",init >( + "Create a Map with a width and height as integers and, optionally,\n" + "an srs string either with a Proj.4 epsg code ('+init=epsg:')\n" + "or with a Proj.4 literal ('+proj=').\n" + "If no srs is specified the map will default to '+proj=latlong +datum=WGS84'\n" + "\n" + "Usage:\n" + ">>> from mapnik import Map\n" + ">>> m = Map(600,400)\n" + ">>> m\n" + "\n" + ">>> m.srs\n" + "'+proj=latlong +datum=WGS84'\n" + )) + + .def_pickle(map_pickle_suite() + ) + + .def("append_style",&Map::insert_style, + "Insert a Mapnik Style onto the map by appending it.\n" + "\n" + "Usage:\n" + ">>> sty\n" + "\n" + ">>> m.append_style('Style Name', sty)\n" + "True # style object added to map by name\n" + ">>> m.append_style('Style Name', sty)\n" + "False # you can only append styles with unique names\n" + ) + + .def("envelope", + make_function(&Map::getCurrentExtent, + return_value_policy()), + "Return the Map Envelope object\n" + "and print the string representation\n" + "of the current extent of the map.\n" + "\n" + "Usage:\n" + ">>> m.envelope()\n" + "Envelope(-0.185833333333,-0.96,0.189166666667,-0.71)\n" + ">>> dir(m.envelope())\n" + "...'center', 'contains', 'expand_to_include', 'forward',\n" + "...'height', 'intersect', 'intersects', 'inverse', 'maxx',\n" + "...'maxy', 'minx', 'miny', 'width'\n" + ) + + .def("find_style", + &Map::find_style, + return_value_policy(), + "Query the Map for a style by name and return\n" + "a style object if found and the default map\n" + "style if not found.\n" + "\n" + "Usage:\n" + ">>> m.find_style('Style Name')\n" + "\n" + ) + + .def("pan",&Map::pan, + "Set the Map center at a given x,y location\n" + "as integers in the coordinates of the pixmap or map surface.\n" + "\n" + "Usage:\n" + ">>> m = Map(600,400)\n" + ">>> m.envelope().center()\n" + "Coord(-0.5,-0.5) # default Map center\n" + ">>> m.pan(-1,-1)\n" + ">>> m.envelope().center()\n" + "Coord(0.00166666666667,-0.835)\n" + ) + + .def("pan_and_zoom",&Map::pan_and_zoom, + "Set the Map center at a given x,y location\n" + "and zoom factor as a float.\n" + "\n" + "Usage:\n" + ">>> m = Map(600,400)\n" + ">>> m.envelope().center()\n" + "Coord(-0.5,-0.5) # default Map center\n" + ">>> m.scale()\n" + "-0.0016666666666666668\n" + ">>> m.pan_and_zoom(-1,-1,0.25)\n" + ">>> m.scale()\n" + "0.00062500000000000001\n" + ) + + .def("query_map_point",&Map::query_map_point, + "Query a Map Layer (by layer index) for features \n" + "intersecting the given x,y location in the coordinates\n" + "of the pixmap or map surface.\n" + "Will return a Mapnik Featureset if successful\n" + "otherwise will return None.\n" + "\n" + "Usage:\n" + ">>> feat = m.query_map_point(0,200,200)\n" + ">>> feat\n" + ">>> \n" + ">>> feat.next()\n" + ">>> \n" + ) + + .def("query_point",&Map::query_point, + "Query a Map Layer (by layer index) for features \n" + "intersecting the given x,y location in the coordinates\n" + "of map projection.\n" + "Will return a Mapnik Featureset if successful\n" + "otherwise will return None.\n" + "\n" + "Usage:\n" + ">>> feat = m.query_point(0,-122,48)\n" + ">>> feat\n" + ">>> \n" + ">>> feat.next()\n" + ">>> \n" + ) + + .def("remove_style",&Map::remove_style, + "Remove a Mapnik Style from the map.\n" + "\n" + "Usage:\n" + ">>> m.remove_style('Style Name')\n" + ) + + .def("scale", &Map::scale, + "Return the Map Scale.\n" + "Usage:\n" + "\n" + ">>> m.scale()\n" + ) + + .def("zoom",&Map::zoom, + "Zoom in by a given factor.\n" + "Usage:\n" + "\n" + ">>> m.zoom(0.25)\n" + ) + + .def("zoom_all",&Map::zoom_all, + "Set the geographical extent of the map\n" + "to the combined extents of all active layers.\n" + "\n" + "Usage:\n" + ">>> m.zoom_all()\n" + ) + + .def("zoom_to_box",&Map::zoomToBox, + "Set the geographical extent of the map\n" + "by specifying a Mapnik Envelope.\n" + "\n" + "Usage:\n" + ">>> extext = Envelope(-180.0, -90.0, 180.0, 90.0)\n" + ">>> m.zoom_to_box(extent)\n" + ) + + .add_property("background",make_function + (&Map::background,return_value_policy()), + &Map::set_background, + "The background color of the map.\n" + "\n" + "Usage:\n" + ">>> m.background = Color('steelblue')\n" + ) + + .add_property("buffer_size", + &Map::buffer_size, + &Map::set_buffer_size, + "Get/Set the size of buffer around map in pixels.\n" + "\n" + "Usage:\n" + ">>> m.buffer_size\n" + "0 # zero by default\n" + ">>> m.buffer_size = 2\n" + ">>> m.buffer_size\n" + "2\n" + ) + + .add_property("height", + &Map::getHeight, + &Map::setHeight, + "Get/Set the height of the map in pixels.\n" + "Minimum settable size is 16 pixels.\n" + "\n" + "Usage:\n" + ">>> m.height\n" + "400\n" + ">>> m.height = 600\n" + ">>> m.height\n" + "600\n" + ) + + .add_property("layers",make_function + (layers_nonconst,return_value_policy()), + "The list of map layers.\n" + "\n" + "Usage:\n" + ">>> m.layers\n" + "" + ">>> m.layers[0]\n" + "\n" + ) + + .add_property("srs", + make_function(&Map::srs,return_value_policy()), + &Map::set_srs, + "Spatial reference in Proj.4 format.\n" + "Either an epsg code or proj literal.\n" + "For example, a proj literal:\n" + "\t'+proj=latlong +datum=WGS84'\n" + "and a proj epsg code:\n" + "\t'+init=epsg:4326'\n" + "\n" + "Note: using epsg codes requires the installation of\n" + "the Proj.4 'epsg' data file normally found in '/usr/local/share/proj'\n" + "\n" + "Usage:\n" + ">>> m.srs\n" + "'+proj=latlong +datum=WGS84' # The default srs if not initialized with custom srs\n" + ">>> # set to google mercator with Proj.4 literal\n" + "... \n" + ">>> m.srs = '+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs +over'\n" + ) + + .add_property("width", + &Map::getWidth, + &Map::setWidth, + "Get/Set the width of the map in pixels.\n" + "Minimum settable size is 16 pixels.\n" + "\n" + "Usage:\n" + ">>> m.width\n" + "600\n" + ">>> m.width = 800\n" + ">>> m.width\n" + "800\n" + ) + ; }