:py:mod:`gnome.utilities.map_canvas` ==================================== .. py:module:: gnome.utilities.map_canvas .. autoapi-nested-parse:: Module to hold classes and suporting code for the map canvas for GNOME: The drawing code for rendering to images in scripting mode, and also for pushing some rendering to the server. Also used for making raster maps. This should have the basic drawing stuff. Ideally nothing in here is GNOME-specific. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: gnome.utilities.map_canvas.MapCanvas gnome.utilities.map_canvas.GridLines gnome.utilities.map_canvas.Viewport .. py:class:: MapCanvas(image_size=(800, 600), projection=None, viewport=None, preset_colors='BW', background_color='transparent', colordepth=8, **kwargs) Bases: :py:obj:`object` A class to draw maps, etc. This class provides the ability to set a projection, and then change the viewport of the rendered map All the drawing methods will project and scale and shift the points so the rendered image is projected and shows only what is in the viewport. In addition, it keeps two image buffers: background and foreground. These can be rendered individually, and saved out either alone or composited. This version uses a paletted (8 bit) image -- may be updated for RGB images at some point. create a new map image from scratch -- specifying the size :param image_size: (width, height) tuple of the image size in pixels Optional parameters :param projection=None: gnome.utilities.projections object to use. if None, it defaults to FlatEarthProjection() :param viewport: viewport of map -- what gets drawn and on what scale. Default is full globe: (((-180, -90), (180, 90))) :param preset_colors='BW': color set to preset. Options are: 'BW' - transparent, black, and white: transparent background 'web' - the basic named colors for the web: transparent background 'transparent' - transparent background, no other colors set None - no pre-allocated colors -- the first one you allocate will be the background color :param background_color = 'transparent': color for the background -- must be a color that exists :param colordepth=8: only 8 bit color supported for now maybe someday, 32 bit will be an option .. py:property:: viewport returns the current value of viewport of map: the bounding box of the image .. py:property:: image_size makes it read-only or we can add a setter to re-size the images if we need that .. py:method:: viewport_to_dict() convert numpy arrays to list of tuples todo: this happens in multiple places so maybe worthwhile to define custom serialize/deserialize -- but do this for now .. py:method:: set_viewport(BB=None, center=None, width=None, height=None) Function to allow the user to set properties of the viewport in meters, or by bounding box :param center: The point around which the viewport is centered :type center: tuple of floats (lon, lat) :param width: Width of the viewport in meters :type width: float :param height: height of the viewport in meters :type height: float :param BB: Bounding box of the viewport (overrides all previous parameters) :type BB: a list of tuples containing of the lower left and top right coordinates: ((min_x, min_y),(max_x, max_y)) .. py:method:: zoom(multiplier) .. py:method:: shift_viewport(delta) .. py:method:: rescale() Rescales the projection to the viewport bounding box. Should be called whenever the viewport changes .. py:method:: add_colors(color_list) Add a list of colors to the pallette :param color_list: list of colors. Each element of the list is a 2-tuple: ('color_name', (r,g,b)) .. py:method:: add_color_ramp(color_scheme, min_val, max_val) generate depth colors to the gd images :param color_scheme: color scheme to render images type: 'magma', 'inferno', 'plasma', 'viridis', 'cividis', 'twilight', 'twilight_shifted', 'turbo' :param min_val: value to map to the first color in the scheme :param max_val: value to map to the last color in the scheme .. py:method:: get_color_names() returns all the names colors .. py:method:: create_images(preset_colors) .. py:method:: back_asarray() return the background image as a numpy array .. py:method:: fore_asarray() return the foreground image as a numpy array .. py:method:: clear_background() .. py:method:: clear_foreground() .. py:method:: copy_back_to_fore() copy the background to the foreground note: this will write over anything on the foreground image .. py:method:: draw_points(points, diameter=1, color='black', shape='round', background=False) Draws a set of individual points all in the same color :param points: a Nx2 numpy array, or something that can be turned into one :param diameter=1: diameter of the points in pixels. :type diameter: integer :param color: a named color. :type color: string :param shape: what shape to draw, options are "round", "x". :type shape: string :param background=False: whether to draw to the background image. :type background: bool .. py:method:: draw_polygon(points, line_color=None, fill_color=None, line_width=1, background=False) Draw a polygon :param points: sequence of points :type points: Nx2 array of integers (or something that can be turned into one) :param line_color=None: the color of the outline :type line_color=None: color name (string) or index (int) :param fill_color=None: the color of the filled polygon :type fill_color: color name (string) or index (int) :param line_width=1: width of line :type line_width: integer :param background=False: whether to draw to the background image. :type background: bool .. py:method:: draw_polyline(points, line_color, line_width=1, background=False) Draw a polyline :param points: sequence of points :type points: Nx2 array of integers (or something that can be turned into one) :param line_color: the color of the outline :type line_color: color name or index :param line_width=1: width of line :type line_width: integer :param background=False: whether to draw to the background image. :type background: bool .. py:method:: draw_text(text_list, size='small', color='black', align='lt', background=None, draw_to_back=False) Draw ascii text to the image :param text_list: sequence of strings to be printed, and the locations they are to be located :type text_list: ['string', (lon, lat)] :param size: size of the text to be printed :type size: one of the following strings: {'tiny', 'small', 'medium', 'large', 'giant'} :param color: color of the text to be printed :type color: a valid color string in the py_gd Image color palettes :param align: sets the principal point of the text bounding box. :type align: one of the following strings: {'lt', 'ct', 'rt', 'r', 'rb', 'cb', 'lb', 'l'} .. py:method:: draw_background() .. py:method:: draw_land() .. py:method:: draw_graticule(background=True) draw a graticule (grid lines) on the map only supports decimal degrees for now... .. py:method:: draw_grid() .. py:method:: draw_tags(draw_to_back=True) .. py:method:: save_background(filename, file_type='png') .. py:method:: save_foreground(filename, file_type='png') save the foreground image to the specified filename :param filename: full path of file to be saved to :type filename: string :param file_type: type of file to save :type file_type: one of the following: {'png', 'gif', 'jpeg', 'bmp'} .. py:method:: save(filename, file_type='png') save the map image to the specified filename This copies the foreground image on top of the background image and saves the whole thing. :param filename: full path of file to be saved to :type filename: string :param file_type: type of file to save :type file_type: one of the following: {'png', 'gif', 'jpeg', 'bmp'} .. py:class:: GridLines(viewport=None, projection=None, max_lines=10, DegMinSec=False) Bases: :py:obj:`object` class to hold logic for determining where the gridlines should be for the graticule Creates a GridLines instance that does the logic for and describes the current graticule :param viewport: bounding box of the viewport in question. :type viewport: tuple of lon/lat :param max_lines: How many lines to be displayed on the longest dimension of the viewport. Graticule will scale up or down only when the number of lines in the viewport falls outside the range. :type max_lines: tuple of integers, (max, min) :param DegMinSec: Whether to scale by Degrees/Minute/Seconds, or decimal lon/lat :type bool .. py:attribute:: DEGREE .. py:attribute:: MINUTE .. py:attribute:: SECOND .. py:attribute:: DMS_STEPS :value: () .. py:attribute:: DMS_COUNT .. py:attribute:: DEGREE .. py:attribute:: TENTH .. py:attribute:: HUNDREDTH .. py:attribute:: THOUSANDTH .. py:attribute:: DEG_STEPS :value: () .. py:attribute:: DEG_COUNT .. py:method:: get_step_size(reference_size) Chooses the interval size for the graticule, based on where the reference size fits into the STEPS table. :param reference_size: the approximate size you want in decimal degrees .. py:method:: get_lines() Computes, builds, and returns a list of lines that when drawn, creates the graticule. The list consists of self.lon_lines vertical lines, followed by self.lat_lines horizontal lines. .. py:method:: refresh_scale() Recomputes the interval and number of lines in each dimension. This should be called whenever the viewport changes. .. py:method:: set_max_lines(max_lines=None) Alters the number of lines drawn. :param max_lines: the maximum number of lines drawn. (Note: this is NOT the number of lines on the screen at any given time. That is determined by the computed interval and the size/location of the viewport) :type max_lines: int .. py:method:: set_DMS(DMS=False) :param DMS: Boolean value that specifies if Degrees/Minutes/Seconds tags are enabled. :type DMS: Bool .. py:method:: get_tags() Returns a list of tags for each line (in the same order the lines are returned) and the position where the tag should be printed. Line labels are anchored at the intersection between the line and the edge of the viewport. This may cause the longitude labels to disappear if the aspect ratio of the image and viewport are identical. .. py:class:: Viewport(BB=None, center=None, width=None, height=None) Bases: :py:obj:`object` Viewport class that defines and manages attribues for a viewport onto a flat 2D map. All points and measurements are in lon/lat Init the viewport. Can initialize with center/width/height, and/or with bounding box. NOTE: Bounding box takes precedence over any previous parameters :param center: The point around which the viewport is centered :type center: a tuple containing an lon/lat coordinate :param width: Width of the viewport (lon) :param height: height of the viewport (lat) :param BB: Bounding box of the viewport (overrides previous parameters) :type BB: a list of lon/lat tuples containing the lower left and top right coordinates .. py:property:: BB .. py:property:: center .. py:property:: width .. py:property:: height .. py:method:: scale(multiplier=1.0) .. py:method:: recompute_dim() .. py:method:: recompute_BB() .. py:method:: aspect_ratio()