The KML reading objects (sarpy.io.kml)

Functionality for exporting certain data elements to a kml document

class sarpy.io.kml.Document(file_name=None, **params)

Bases: object

The main kml document container, and zip archive if the output file is of type kmz. This is intended to be used as a context manager.

write_file_to_archive(archive_path, file_path)

Copy the given file into the kmz archive at the given archive location.

Parameters:

  • archive_path (str) – The location in the archive.

  • file_path (str) – The file location on the file system.

Return type:

None

write_string_to_archive(archive_path, val)

Write the given string/bytes into the kmz archive at the given location.

Parameters:

  • archive_path (str) –

  • val (bytes|str) –

Return type:

None

write_image_to_archive(archive_path, val, img_format='PNG')

Write the given PIL image into the kmz archive at the given location.

Parameters:

  • archive_path (str) –

  • val (PIL.Image.Image) –

  • img_format (str) –

Return type:

None

add_container(par=None, the_type='Placemark', **params)

For creation of Document, Folder, or Placemark container.

Parameters:

  • par (None|minidom.Element) –

  • the_type (str) – One of “Placemark”, “Folder”. The type “Document” can only be used once, for the top level construct.

  • params – The dictionary of parameters

Return type:

minidom.Element

add_style_map(style_id, high_id, low_id)

Creates a styleMap from two given style ids.

Parameters:

  • style_id (str) –

  • high_id (str) –

  • low_id (str) –

Return type:

None

add_style(style_id, **params)

Creates a style for use in the document tree.

Parameters:

  • style_id (str) – the style id string.

  • params – the dictionary of the parameters

Return type:

None

add_line_style(style_id=None, par=None, **params)

Add line style.

Parameters:

  • style_id (None|str) – The id, which should not be set if this is a child of a style element.

  • par (None|minidom.Element) – The parent node.

  • params – The parameters dictionary.

Return type:

None

add_list_style(style_id=None, par=None, **params)

Add list style

Parameters:

  • style_id (None|str) – The id, which should not be set if this is a child of a style element.

  • par (None|minidom.Element) – The parent node.

  • params – The parameters dictionary.

Return type:

None

add_label_style(style_id=None, par=None, **params)

Add label style

Parameters:

  • style_id (None|str) – The id, which should not be set if this is a child of a style element.

  • par (None|minidom.Element) – The parent node.

  • params – The parameters dictionary.

Return type:

None

add_icon_style(style_id=None, par=None, **params)

Add icon style.

Parameters:

  • style_id (None|str) – The id, which should not be set if this is a child of a style element.

  • par (None|minidom.Element) – The parent node.

  • params – The parameters dictionary.

Return type:

None

add_poly_style(style_id=None, par=None, **params)

Add poly style.

Parameters:

  • style_id (None|str) – The id, which should not be set if this is a child of a style element.

  • par (None|minidom.Element) – The parent node.

  • params – The parameters dictionary.

Return type:

None

add_default_style()

Add default style

The style is created, and appended at root level. The corresponding styleUrl is ‘#defaultStyle’

add_color_ramp(colors, high_size=1.0, low_size=0.5, icon_ref=None, name_stem='sty')

Adds collection of enumerated styles corresponding to provided array of colors.

Parameters:

  • colors (numpy.ndarray) – numpy array of shape (N, 4) of 8-bit colors assumed to be RGBA

  • high_size (float) – The highlighted size.

  • low_size (float) – The regular (low lighted?) size.

  • icon_ref (str) – The icon reference.

  • name_stem (str) – The string representing the naming convention for the associated styles.

Return type:

None

add_schema(schema_id, field_dict, short_name=None)

For defining/using the extended data schema capability. Note that this is specifically part of the google earth extension of kml, and may not be generally supported by anything except google earth.

Parameters:

  • schema_id (str) – the schema id - must be unique to the id collection document

  • field_dict (dict) –

    dictionary where the key is field name. The corresponding value is a tuple of the form (type, displayName), where displayName can be None. The value of type is one of the data types permitted:

    • ’string’

    • ’int

    • ’uint’

    • ’short’

    • ’ushort’

    • ’float’

    • ’double’

    • ’bool’

  • short_name (None|str) – optional short name for display in the schema

Return type:

None

add_screen_overlay(image_ref, par=None, **params)

Adds ScreenOverlay object.

Parameters:

  • image_ref (str) – Reference to appropriate image object, whether in the kmz archive or an appropriate url.

  • par (None|minidom.Element) – The parent node. Appended at root level if not provided.

  • params – The parameters dictionary.

Return type:

minidom.Element

add_multi_geometry(par=None, **params)

Adds a MultiGeometry object. The MultiGeometry object is really just a container. The user must continue adding the primitive Geometry constituents to this container or nothing will actually get rendered.

Parameters:

  • par (None|minidom.Element) – The parent node. If not given, then a Placemark is created.

  • params – The parameters dictionary

Return type:

minidom.Element

add_polygon(outer_coords, inner_coords=None, par=None, **params)

Adds a Polygon element - a polygonal outer region, possibly with polygonal holes removed

Parameters:

  • outer_coords (str) –

    comma/space delimited string of coordinates for the outerRing. Format of the string 'lon1,lat1,alt1 lon2,lat2,alt2 ...' with the altitude values optional. If given, the altitude value is in meters. The precise interpretation of altitude (relative to the ground, relative to sea level, etc.) depends on the value of relevant tags passed down to the LinearRing objects, namely the values for the params entries:

    • ’extrude’

    • ’tessellate’

    • ’altitudeMode’

  • inner_coords (None|List[str]) – If provided, the coordinates for inner rings.

  • par (None|minidom.Element) – The parent node. If not given, then a Placemark is created.

  • params – The parameters dictionary.

Return type:

minidom.Element

add_linear_ring(coords, par=None, **params)

Adds a LinearRing element (closed linear path).

Parameters:

  • coords (str) –

    comma/space delimited string of coordinates for the outerRing. Format of the string 'lon1,lat1,alt1 lon2,lat2,alt2 ...' with the altitude values optional. If given, the altitude value is in meters. The precise interpretation of altitude (relative to the ground, relative to sea level, etc.) depends on the value of relevant tags passed down to the LinearRing objects, namely the values for the params entries:

    • ’extrude’

    • ’tessellate’

    • ’altitudeMode’

  • par (None|minidom.Element) – The parent node. If not given, then a Placemark is created.

  • params – The parameters dictionary.

Return type:

minidom.Element

add_line_string(coords, par=None, **params)

Adds a LineString element (linear path).

Parameters:

  • coords (str) –

    comma/space delimited string of coordinates for the outerRing. Format of the string 'lon1,lat1,alt1 lon2,lat2,alt2 ...' with the altitude values optional. If given, the altitude value is in meters. The precise interpretation of altitude (relative to the ground, relative to sea level, etc.) depends on the value of relevant tags passed down to the LinearRing objects, namely the values for the params entries:

    • ’extrude’

    • ’tessellate’

    • ’altitudeMode’

  • par (None|minidom.Element) – The parent node. If not given, then a Placemark is created.

  • params – The parameters dictionary.

Return type:

minidom.Element

add_point(coords, par=None, **params)

Adds a Point object.

Parameters:

  • coords (str) –

    comma/space delimited string of coordinates for the outerRing. Format of the string 'lon1,lat1,alt1 lon2,lat2,alt2 ...' with the altitude values optional. If given, the altitude value is in meters. The precise interpretation of altitude (relative to the ground, relative to sea level, etc.) depends on the value of relevant tags passed down to the LinearRing objects, namely the values for the params entries:

    • ’extrude’

    • ’tessellate’

    • ’altitudeMode’

  • par (None|minidom.Element) – The parent node. If not given, then a Placemark is created.

  • params – The parameters dictionary.

Return type:

minidom.Element

add_gx_multitrack(par=None, **params)

Adds a MultiTrack from the gx namespace. This is only a container, much like a MultiGeometry object, which requires the addition of gx:Track objects. Note that this is specifically part of the google earth extension of kml, and may not be generally supported by anything except google earth.

Parameters:

  • par (None|minidom.Element) – The parent node. If not given, then a Placemark is created.

  • params – The parameters dictionary.

Return type:

minidom.Element

add_gx_track(coords, whens, angles=None, par=None, **params)

Adds a Track from the gx namespace. Note that this is specifically part of the google earth extension of kml, and may not be generally supported by anything except google earth.

Parameters:

  • coords (List[str]) –

    list of comma delimited string of coordinates. Format of each string entry: ‘lon1,lat1,alt1’ with altitude values optional. If given, the altitude value is in meters. The precise interpretation of altitude (relative to the ground, relative to sea level, etc.) depends on the value of relevant tags passed down to the LinearRing objects, namely the values for the params entries:

    • ’extrude’

    • ’tessellate’

    • ’altitudeMode’

  • whens (List[str]) – list of iso-formatted time strings - entries matching coords

  • angles (None|List[str]) – None or list of heading (rotation) angles for the icon. If None, then Google Earth infers from the path.

  • par (None|minidom.Element) – The parent node. If not given, then a Placemark is created.

  • params – The parameters dictionary.

Return type:

minidom.Element

add_ground_overlay(image_ref, bounding_box=None, lat_lon_quad=None, par=None, **params)

Adds GroundOverlay object, defined either from a bounding_box or a lat/lon quadrilateral.

Parameters:

  • image_ref (str) – Reference to appropriate image object, either in the kmz archive or an appropriate url.

  • bounding_box (None|numpy.ndarray|tuple|list) – list of the form [latitude max, latitude min, longitude max, longitude min]

  • lat_lon_quad (None|numpy.ndarray|list|tuple) – list of the form [[latitude, longitude]], must have 4 entries. The orientation is counter-clockwise from the lower-left image corner.

  • par (None|minidom.Element) – The parent node. if not provided, then a Placemark object is created implicitly.

  • params – The parameters dictionary.

Return type:

minidom.Element

add_region(par, **params)

Adds a region element.

Parameters:

  • par (None|minidom.Element) –

  • params –

Return type:

minidom.Element

add_regionated_ground_overlay(img, par, bounding_box=None, lat_lon_quad=None, img_format='PNG', nominal_image_size=1024, **params)

Adds regionated GroundOverlay objects. This downsamples the image to a pyramid type collection of smaller images, and defines the regions. Requires viable archive.

Parameters:

  • img (PIL.Image.Image) – the image instance.

  • par (minidom.Element) – the parent node, a folder object will be created and appended to par. The overlays will be added below this folder.

  • bounding_box (None|numpy.ndarray) – Follows the format for the argument in add_ground_overlay().

  • lat_lon_quad (None|nunpy.ndarray) – Follows the format for the argument in add_ground_overlay().

  • img_format (str) –

    string representing a viable Image format. The viable options that will be allowed:

    • ’PNG’ - (default) transparency; lossless; good compression

    • ’TIFF’ - supports transparency; lossless; poor compression

    • ’JPEG’ - no transparency; lossy; best compression

    • ’GIF’ - transparency; lossless; medium compression

    The PIL library actually supports a much larger collection of image formats, but the remaining formats are not good candidates for this application.

  • nominal_image_size (int) – The nominal image size for splitting. A minimum of 512 will be enforced.

  • params – The parameters dictionary.

Return type:

minidom.Element