Merge pull request #44 from yufeizhu600/feature_add_poi

Fix adding textbox in the add_points method

docs/source/points.rst

@@ -1,8 +1,8 @@
-Custom points with or without textbox
---------------------------------
+Add custom points with descriptions
+-----------------------------------
 
 Pycoast can add a symbol to points of interest on an image. The following examples show how
-we might use the :meth:`~pycoast.cw_agg.ContourWriterAGG.add_points`  method to annotate the
+we might use the :meth:`~pycoast.cw_agg.ContourWriterAGG.add_points` method to annotate the
 points on an image.
 
 First of all, we setup a PIL image with an area definition, then we add coastlines and
@@ -19,7 +19,7 @@ borders for reference.
     >>> cw.add_borders(img, area_def, outline='black', width=3, level=1, resolution='c')
 
 Now we can add a circle, which is the default symbol, with default point size 6 at the
-location of Berlin, the name of the lacation will marked in a text box with black borders
+location of Berlin, the name of the location will marked in a text box with black borders
 and the default text size is 12.
 
     >>> points_list = [((13.4050, 52.5200), 'Berlin')]
@@ -39,14 +39,14 @@ Similarly, assign the description as an empty string will only draw the symbol o
 The example below will draw a square symbol at the location of Paris.
 
     >>> points_list = [((2.3522, 48.8566), '')]
-    >>> cw.add_points(pil_img, area, points_list=points_list,i
+    >>> cw.add_points(pil_img, area, points_list=points_list,
     ...               font_file=font_file,
     ...               symbol='square', ptsize=10,
     ...               outline='red', width=1,
     ...               fill='blue', fill_opacity=128)
 
-Finally, we can fully costomize the annotation as the example below, which will add
-a circle in black with linewidth set to 2 and filled in red color with opacity equals 255;
+Finally, we can fully customize the annotation as the example below, which will add
+a circle in black with line width set to 2 and filled in red color with opacity equals 255;
 the description will be 'London' in a textbox with blue borders and filled with green color
 with opacity set to 128.
 
@@ -62,7 +62,27 @@ with opacity set to 128.
 
 .. image:: images/nh_points_agg.png
 
-The :meth:`~pycoast.cw_agg.ContourWriterAGG.add_points` method accepts a list of longitude, latitude pairs, with an optional
-Description string.
+
+Please check out the docstrings of the :meth:`~pycoast.cw_agg.ContourWriterAGG.add_points`
+function for the full description of the parameters.
+
+Moreover, we can organize the overlay parameters in a dictionary and use :meth:`~pycoast.cw_agg.ContourWriterAGG.add_overlay_from_dict`
+to apply the overlays in one shot.
+
+    >>> points = {'points_list': [((2.3522, 48.8566), 'Paris'), ((0.1278, 51.5074), 'London')],
+    ...           'font': font_file,
+    ...           'symbol': 'circle', 'ptsize': 16,
+    ...           'outline': 'black', 'width': 3,
+    ...           'fill': 'red', 'fill_opacity': 128,
+    ...           'box_outline': 'blue', 'box_linewidth': 0.5,
+    ...           'box_fill': 'yellow', 'box_opacity': 200}
+
+    >>> overlays = {'coasts': {'outline': 'black', 'level': 4, 'resolution': 'l'},
+    ...             'borders': {'outline': 'black', 'width': 3, 'level': 1, 'resolution': 'c'},
+    ...             'points': points}
+
+    >>> img = cw.add_overlay_from_dict(overlays, area_def)
+
+    >>> img.save('./add_overlays_from_dict.png')
 
 .. _PIL: http://www.pythonware.com/products/pil/

pycoast/cw_base.py

@@ -834,18 +834,18 @@ def add_overlay_from_dict(self, overlays, area_def, cache_epoch=None, background
 
             params = overlays['points'].copy()
 
-            points_list = list(params.pop('list'))
+            points_list = list(params.pop('points_list'))
             font_file = params.pop('font')
             font_size = int(params.pop('font_size', DEFAULT_FONTSIZE))
 
             symbol = params.pop('symbol', DEFAULT_SYMBOL)
-            pt_size = int(params.pop('pt_size', DEFAULT_PTSIZE))
+            ptsize = int(params.pop('ptsize', DEFAULT_PTSIZE))
 
             outline = params.pop('outline', DEFAULT_OUTLINE)
             fill = params.pop('fill', DEFAULT_FILL)
 
             self.add_points(foreground, area_def, points_list, font_file, font_size,
-                            symbol, pt_size, outline, fill, **params)
+                            symbol, ptsize, outline, fill, **params)
 
         # Grids overlay
         if 'grid' in overlays:
@@ -1072,12 +1072,14 @@ def add_points(self, image, area_def, points_list, font_file, font_size=12,
                     text_position = [x + ptsize, y]  # draw the text box next to the point
                     font = self._get_font(outline, font_file, font_size)
 
-                    box_outline = kwargs.pop('box_outline', 'white')
-                    box_opacity = kwargs.pop('box_opacity', 0)
+                    new_kwargs = kwargs.copy()
+
+                    box_outline = new_kwargs.pop('box_outline', 'white')
+                    box_opacity = new_kwargs.pop('box_opacity', 0)
 
                     # add text_box
                     self._draw_text_box(draw, text_position, desc, font, outline,
-                                        box_outline, box_opacity, **kwargs)
+                                        box_outline, box_opacity, **new_kwargs)
 
             logger.debug("Point %s has been added to the image", str((lon, lat)))
 

pycoast/tests/nh_points_agg.ini

@@ -10,10 +10,10 @@ width = 3
 resolution = c
 
 [points]
-list = ((2.3522, 48.8566), 'Paris'), ((0.1278, 51.5074), 'London')
+points_list = ((2.3522, 48.8566), 'Paris'), ((0.1278, 51.5074), 'London')
 font = 'pycoast/tests/test_data/DejaVuSerif.ttf'
 symbol = circle
-pt_size = 16
+ptsize = 16
 outline = black
 width = 3
 fill = red

pycoast/tests/nh_points_pil.ini

@@ -10,10 +10,10 @@ width = 3
 resolution = c
 
 [points]
-list = ((13.4050, 52.5200), 'Berlin'), ((12.4964, 41.9028), 'Rome')
+points_list = ((13.4050, 52.5200), 'Berlin'), ((12.4964, 41.9028), 'Rome')
 font = 'pycoast/tests/test_data/DejaVuSerif.ttf'
 symbol = square
-pt_size = 6
+ptsize = 6
 outline = red
 fill = yellow
 box_outline = black

pycoast/tests/test_pycoast.py

@@ -585,9 +585,9 @@ def test_grid_agg_txt(self):
         cw = ContourWriterAGG(gshhs_root_dir)
 
         cw.add_coastlines(img, area_def, resolution='l', level=4)
-        font = aggdraw.Font('blue', os.path.join(os.path.dirname(__file__),
-                                                 'test_data',
-                                                 'DejaVuSerif.ttf'), size=16,
+        font = aggdraw.Font('blue',
+                            os.path.join(os.path.dirname(__file__), 'test_data', 'DejaVuSerif.ttf'),
+                            size=16,
                             opacity=200)
         cw.add_grid(img, area_def, (10.0, 10.0), (2.0, 2.0), font=font,
                     outline='blue', outline_opacity=255, width=1.0,
@@ -815,7 +815,7 @@ def test_config_file_points_and_borders_agg(self):
                                    'nh_points_agg.ini')
 
         grid_img = Image.open(os.path.join(os.path.dirname(__file__),
-                                           'nh_points_cfg_agg.png'))
+                                           'nh_points_agg.png'))
         grid_data = np.array(grid_img)
 
         img = Image.new('RGB', (1024, 1024), (255, 255, 255))
@@ -833,7 +833,7 @@ def test_config_file_points_and_borders_agg(self):
 
         res = np.array(img)
         self.assertTrue(fft_metric(grid_data, res),
-                        'Writing of nh points with agg module failed')
+                        'Add points with agg module from a config file failed')
 
     def test_coastlines_convert_to_rgba_agg(self):
         from pycoast import ContourWriterAGG