sij/mapnik
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #2431 from joto/doc-fixes

Browse source 
Various doc fixes.
This commit is contained in:
Artem Pavlenko 2014-09-23 15:15:06 +01:00
commit 5e00bb47bd
2 changed files with 17 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/contributing.markdown
View file

@ -17,6 +17,8 @@ Also read the design philosophy page for the motivations that lead to code decis
Templates are good, within reason. We seek to use templates where possible for flexible code, but not in cases where functional patterns would be just as concise and clear. Templates are good, within reason. We seek to use templates where possible for flexible code, but not in cases where functional patterns would be just as concise and clear.
Since version 3.0 we use C++11 which brings many advantages and makes the code easier to write and to read.
In general we use Boost, it makes more possible in C++. It is a big build time dependency (as in time to compile against and # of headers) but ultimately compiles to small object code and is very fast (particularly spirit). It also has no dependencies itself (it's really an extension to the C++ language) so requiring it is much easier than requiring a hard dependency that itself has other dependencies. This is a big reason that we prefer AGG to Cairo as our primary renderer. Also AGG produces the best visual output and strikes an excellent balance between speed and thread safety by using very lightweight objects. Cairo not so much. In general we use Boost, it makes more possible in C++. It is a big build time dependency (as in time to compile against and # of headers) but ultimately compiles to small object code and is very fast (particularly spirit). It also has no dependencies itself (it's really an extension to the C++ language) so requiring it is much easier than requiring a hard dependency that itself has other dependencies. This is a big reason that we prefer AGG to Cairo as our primary renderer. Also AGG produces the best visual output and strikes an excellent balance between speed and thread safety by using very lightweight objects. Cairo not so much.
You will also notice that we don't use many of the standard geo libraries when we could. For instance we don't use GDAL, OGR, or GEOS anywhere in core, and only leverage them in optional plugins. We feel we can often write code that is faster and more thread safe than these libraries but that still does the job. If this ever changes we can adapt and start using these libraries or others as dependencies - nothing is nicer than standing on the shoulders of giants when it makes sense. You will also notice that we don't use many of the standard geo libraries when we could. For instance we don't use GDAL, OGR, or GEOS anywhere in core, and only leverage them in optional plugins. We feel we can often write code that is faster and more thread safe than these libraries but that still does the job. If this ever changes we can adapt and start using these libraries or others as dependencies - nothing is nicer than standing on the shoulders of giants when it makes sense.
@ -102,20 +104,26 @@ which triggers locks
(int)value; // no (int)value; // no
#### Use const keyword after the type #### Use const keyword after the type
std::string const& variable_name // preferred, for consistency std::string const& variable_name // preferred, for consistency
const std::string & variable_name // no const std::string & variable_name // no
#### Pass built-in types by value, all others by const& #### Pass built-in types by value, all others by const&
void my_function(int double val); // if int, char, double, etc pass by value void my_function(int double val); // if int, char, double, etc pass by value
void my_function(std::string const& val); // if std::string or user type, pass by const& void my_function(std::string const& val); // if std::string or user type, pass by const&
#### Shared pointers should be created with [boost::make_shared](http://www.boost.org/doc/libs/1_47_0/libs/smart_ptr/make_shared.html) where possible #### Shared pointers should be created with [boost::make_shared](http://www.boost.org/doc/libs/1_47_0/libs/smart_ptr/make_shared.html) where possible
Since Mapnik 3.0 use std::make_shared.
#### Use assignment operator for zero initialized numbers #### Use assignment operator for zero initialized numbers
double num = 0; // please double num = 0; // please
@ -129,18 +137,21 @@ which triggers locks
void foo (int a) // no void foo (int a) // no
#### Separate arguments by a single space: #### Separate arguments by a single space:
void foo(int a, float b) // please void foo(int a, float b) // please
void foo(int a,float b) // no void foo(int a,float b) // no
#### Space between operators: #### Space between operators:
if (a == b) // please if (a == b) // please
if(a==b) // no if(a==b) // no
#### Braces should always be used: #### Braces should always be used:
if (!file) if (!file)
@ -160,6 +171,7 @@ which triggers locks
// more... // more...
} }
#### Prefer `empty()` over `size() == 0` if container supports it #### Prefer `empty()` over `size() == 0` if container supports it
This avoids implicit conversions to bool and reduces compiler warnings. This avoids implicit conversions to bool and reduces compiler warnings.
@ -171,8 +183,7 @@ This avoids implicit conversions to bool and reduces compiler warnings.
### Other C++ style resources ### Other C++ style resources
Many also follow the useful [google](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) which mostly fits our style. However, Google obviously has to maintain a lot of aging codebases. Mapnik can move faster, so we don't follow all Many also follow the useful [Google style guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) which mostly fits our style. However, Google obviously has to maintain a lot of aging codebases. Mapnik can move faster, so we don't follow all of those style recommendations.
of those style recommendations.
### Emacs helper ### Emacs helper

8
docs/design.markdown
View file

@ -1,19 +1,19 @@
# Design philosophy # Design philosophy
Above all Mapnik is about making beautiful maps. This aim drives us to be constantly forward looking. Progress in technology and design are reshaping the art of the possible for maps. Mapnik joins the best ideas in high quality graphics with robust patterns and algorithms for spatial data access. The goal should be no less than enabling a new generation of map makers and gorgous maps. Above all Mapnik is about making beautiful maps. This aim drives us to be constantly forward looking. Progress in technology and design are reshaping the art of the possible for maps. Mapnik joins the best ideas in high quality graphics with robust patterns and algorithms for spatial data access. The goal should be no less than enabling a new generation of map makers and gorgeous maps.
Mapnik is a library. It is not a server - rather it's for writing servers. Or for writing desktop graphics engines to display maps. Or for visualizing new galaxies - its up to you. If you have an inclination for scripting and something to render in real world or celestial coordinates, Mapnik is for you. Mapnik is not a full solution, or even half a solution. At its best, Mapnik is a drawing api that provides the right tools for the developer to make sense of, and art from, geodata. Mapnik is a library. It is not a server - rather it's for writing servers. Or for writing desktop graphics engines to display maps. Or for visualizing new galaxies - its up to you. If you have an inclination for scripting and something to render in real world or celestial coordinates, Mapnik is for you. Mapnik is not a full solution, or even half a solution. At its best, Mapnik is a drawing api that provides the right tools for the developer to make sense of, and art from, geodata.
But Mapnik is not just about drawing on a canvas. Beautiful maps can also be interactive maps and Mapnik aims to provide very flexible, custom access to geo features both in its C++ api and in binding languages. MetaWriters and the Grid renderer are two recent advances that enable highly interactive feature display in mapping applications using JSON serialized features, but more will come. But Mapnik is not just about drawing on a canvas. Beautiful maps can also be interactive maps and Mapnik aims to provide very flexible, custom access to geo features both in its C++ api and in binding languages. MetaWriters and the Grid renderer are two recent advances that enable highly interactive feature display in mapping applications using JSON serialized features, but more will come.
Mapnik core is simple set of objects providing structures for features and the ability to query, filter, cache, and render them. This design can be lightweight, flexible, and high performance because the core library does have to worry about where data comes from or where it goes after rendering. Datasources are separate plugin libraries loaded at runtime that, when called, provide feature arrays. The core classes make no assumptions about map size, format, or projection. The core is designed to make writing a high performance tile server, that renders on-demand and uses multi-threaded or multi-process concurrency, as easy as possible. Mapnik core is a simple set of objects providing structures for features and the ability to query, filter, cache, and render them. This design can be lightweight, flexible, and high performance because the core library does not have to worry about where data comes from or where it goes after rendering. Datasources are separate plugin libraries loaded at runtime that, when called, provide feature arrays. The core classes make no assumptions about map size, format, or projection. The core is designed to make writing a high performance tile server, that renders on-demand and uses multi-threaded or multi-process concurrency, as easy as possible.
Chasing beauty and speed, as technology advances, requires experimentation and a Chasing beauty and speed, as technology advances, requires experimentation and a
frequent stream of new ideas. To write fast and creative code we strive to avoid hard dependencies on older libraries or libraries that attempt to do too much at the cost of performance. At the same time, to be able to maintain ambitious goals we cannot write boilerplate code or attempt to write robust code for domains outside of mapping and graphics. As such we rely as much as possible on the Boost libraries. frequent stream of new ideas. To write fast and creative code we strive to avoid hard dependencies on older libraries or libraries that attempt to do too much at the cost of performance. At the same time, to be able to maintain ambitious goals we cannot write boilerplate code or attempt to write robust code for domains outside of mapping and graphics. As such we rely as much as possible on the Boost libraries.
Mapnik is cross platform because the C++ language and the Boost makes this feasible Mapnik is cross platform because the C++ language and Boost makes this feasible
enough it would be a shame not to be. But our development target is the latest enough it would be a shame not to be. But our development target is the latest
release of linux, particularly server based distributions, and many Mapnik developers release of Linux, particularly server based distributions, and many Mapnik developers
use OSX as a development environment. use OSX as a development environment.
If you are having fun using Mapnik, stick with it. But, Mapnik is not always the right tool, of course. If you have small sets of data (MB's), try just rendering it in a web browser client using a javascript mapping api. Or if you need to set up an array of OGC Web services, use GeoServer. Lastly, if you are looking for a full solution for web cartography, use TileMill. If you are having fun using Mapnik, stick with it. But, Mapnik is not always the right tool, of course. If you have small sets of data (MB's), try just rendering it in a web browser client using a javascript mapping api. Or if you need to set up an array of OGC Web services, use GeoServer. Lastly, if you are looking for a full solution for web cartography, use TileMill.