A Python library for creating 3d floating polygons and circles in .kml for Google Earth.
Project description
KML+
KML+ (KMLPlus) is library of code for Python which allows the user to easily process_points standard and 'floating' Polygons, Circles and Arcs.
Table of Contents
Who is this for
This is for anyone who wishes to easily render polygons, especially 'floating' or curved polygons within Google Earth.
I work in the aviation industry and needed a reliable way to process_points models of our airspace. It its useful for creating models of airways and controlled airspace. It can be used for anything that takes your fancy!
Installing
Pip
pip install kmlplus==2.1.0 <--- last stable release
pip install kmlplus==3.0.0b5 <--- Current v3.0.0-beta.5
Clone
git clone https://github.com/MHenderson1988/kmlplus.git
# Or
git clone git@github.com:MHenderson1988/kmlplus.git
Running tests
python -m unittest
Usage v3
Recommendations
KML+ easily integrates with the fantastic Simplekml library and I highly recommend using it in conjunction with KML+ for the best experience.
Coordinates
Coordinates should always be passed as a single or multiple strings within a list in x, y, z(optional) format. Both Degrees Minutes Seconds (DDMMSS.ss) and Decimal Degres (DD.dd) are accepted. DMS should be suffixed with N, W, S or E. Decimal degrees are suffixed using -/+ convention.
While a coordinate string must be passed using the same type of coordinate, lists can contain a mixture of DMS and DD coordinates and will convert appropriately.
If no z value is provided, defaults to 0.0.
Example
[
'553124N 0045830W',
'552040N 0042722W',
'551848N 0044702W',
'553124N 0045830W'
]
Coordinates containing Arcs
When creating a curved segment of a polygon, the string should be passed as follows -
'start=[starting_coordinate], end=[ending_coordinate], centre=[centre_coordinate], direction=[clockwise/anticlockwise]'
Example -
[
'start=54.32111 -3.98721, end=54.13447 -3.89329, centre=54.31667 -3.41806, direction=anticlockwise',
'54.13444 -3.89333',
'54.17417 -4.14556',
'start=54.17418 -4.14551, end=54.23696 -4.17352, centre=54.31667 -3.41806, direction=clockwise',
'54.23694 -4.17361',
'54.32111 -3.98722',
]
Classes and functions
v3.0 has stripped back to one single class which contains functions to process_points points, circles, cylinders, polygons, polyhedrons and linestrings.
KmlPlus (Class)
from kmlplus.kml import KmlPlus
KmlPlus(self, save_name='KmlPlus', output_path=None)
KmlPlus is the class through which you process_points your 2D and 3D geometries.
- save_name accepts a string and is used for naming the resulting .kml file.
- output_path accepts a string representing the directory the resulting .kml shall be saved to.
KmlPlus (functions)
linestring(coordinate_list, **kwargs)
The linestring function updates the kml file with a KML linestring feature.
from kmlplus.kml import KmlPlus
"""
Args:
coordinate_list (list): A list containing a single coordinate
Keyword Args:
uom: The unit of measurement for the Z value. Default is metres (M).
z (int): The Z value for the point. Default is 0.
fol (str): A string to name the folder in which the point is stored.
linestring_name (str): String to name the LineString object
colour_hex (str): String representing a colour hex
extrude (int): 1 or 0, Whether to extrude the point
width(int): Line width
altitude_mode(str): Accepts simplekml Altitude mode options
Returns:
None
"""
kml_file = KmlPlus('Point Styling.kml')
kml_file.linestring(coordinates_list)
polyhedron(coordinate_list, **kwargs)
Updates the KmlFile with a polyhedron based upon the coordinates and optional upper and lower limits.
"""
Args:
lower_coordinate_list: List of coordinates for the lower polygon
upper_coordinate_list: List of coordinates for the upper polygon
Keyword Args:
fol (str): A string to name the folder in which the point is stored.
lower_polygon_name (str): Lower polygon object name
upper_polygon_name (str): Upper polygon object name
lower_layer (str): Lower layer z value, default is 0
upper_layer (str): Upper layer z value, default is 0
lower_layer_uom (str): Lower layer unit of measure, default is M
upper_layer_uom (str): Upper layer unit of measure, default is M
colour_hex (str): String representing a colour hex
fill (str): 1 or 0, whether or not to fill the polygon
outline (str): 1 or 0, whether to include outline of polygon
extrude (str): 1 or 0, Whether to extrude the point
altitude_mode (str): Accepts simplekml Altitude mode options
Returns:
None
"""
kml_file = KmlPlus('Point Styling.kml')
kml_file.polyhedron(coordinates_list, lower_layer = 2000, upper_layer = 5000)
circle(coordinate_list, radius, **kwargs)
Creates a 2D circle. Coordinate list contains a single set of coordinates in x, y, z format.
"""
Args:
coordinate_list (list): A list containing a single set of coordinates which is the centre point of the circle
radius (float): The radius of the circle
Keyword Args:
z (float): The Z value for the circle. Default is 0.
fol (str): Name of the folder in which the KML objects are stored.
name (str): What to name the Circle object
uom (str): The unit of measurement of z. Accepted arguments are 'FT', 'NM', 'MI', 'KM' and 'M'.
Defaults to metres
radius_uom (str): The unit of measurement of the radius. Accepted arguments are 'FT', 'NM', 'MI', 'KM' and 'M'.
Defaults to metres
colour_hex (str): String representing a colour hex
extrude (int): 1 or 0, Whether to extrude the point
altitude_mode (str): Accepts simplekml Altitude mode options
Returns:
None
"""
kml_file = KmlPlus('Point Styling.kml')
kml_file.circle(coordinates_list, 500)
cylinder(coordinate_list, radius, **kwargs)
Creates a Cylinder from a single set of coordinates within a list.
"""
Args:
coordinate_list: A list containing a single set of coordinates representing the centre of the circle
radius: The radius of the circle
Keyword Args:
lower_layer (float): Height/Altitude of the lower layer
upper_layer (float): Height/Altitude of the upper layer
sample (int): How many points to use when creating the circles which make up the cylinder
lower_circle_name (str): Lower circle object name
upper_circle_name (str): Upper circle object name
radius_uom (str): Radius unit of measure.
fol (str): Name of the folder in which the KML objects are stored.
uom (str): The unit of measurement of the radius. Accepted arguments are 'FT', 'NM', 'MI', 'KM' and 'M'.
Defaults to 'NM'
colour_hex (str): String representing a colour hex
fill (str): 1 or 0, whether or not to fill the polygon
outline (str): 1 or 0, whether to include outline of polygon
altitude_mode (str): Accepts simplekml Altitude mode options
Returns:
None
"""
kml_file = KmlPlus('Point Styling.kml')
kml_file.cylinder(coordinates_list, 500, lower_layer=50, upper_layer=500)
point(coordinate_list, **kwargs)
Creates a single point from a single set of coordinates stored in a list in x, y, z format.
"""
Args:
coordinate_list (list): A list containing a single coordinate. Z values are to be given
in metres (M).
Keyword Args:
fol (str): A string to name the folder in which the point is stored.
z (float): The Z value for the point. Default is 0.
uom (str): The unit of measurement for the Z value. Default is metres (M).
point_name (str): String to name the point object
colour_hex (str): String representing a colour hex
extrude (int): 1 or 0, Whether to extrude the point
altitude_mode (str): Accepts simplekml Altitude mode options
Returns:
None
"""
point = PointFactory(coordinate_list).process_coordinates()
fol = self.kml.newfolder(name=kwargs.get('fol', 'KmlPlus Point'))
pnt = fol.newpoint(name=kwargs.get('point_name', 'KmlPlus Point'))
pnt.coords = [(point[0].x, point[0].y, point[0].z)]
pnt.style.color = kwargs.get('colour_hex', '7Fc0c0c0')
pnt.extrude = kwargs.get('extrude', 0)
pnt.altitudemode = kwargs.get('altitude_mode', simplekml.AltitudeMode.relativetoground)
self.kml.save(self.save_name)
kml_file = KmlPlus('Point Styling.kml')
kml_file.point(coordinates_list)
Example script
kml_file = KmlPlus(file_name='Point Styling.kml')
kml_file.linestring(test_data.birmingham_cta_9, uom='FT')
kml_file.cylinder(test_data.beccles_parachute, 50000, upper_layer=5000)
kml_file.point(test_data.beccles_parachute)
kml_file.polyhedron(test_data.birmingham_cta_10, lower_layer=6500, upper_layer=10500,
name='Birmingham CTA 10')
kml_file.polyhedron(test_data.birmingham_cta_9, lower_layer=6500, upper_layer=8500,
name='Birmingham CTA 9')
kml_file.polyhedron(test_data.prestwick_cta_1, lower_layer=1500, upper_layer=5500, name='Prestwick CTA 1')
kml_file.polyhedron(test_data.prestwick_cta_2, lower_layer=2000, upper_layer=5500, name='Prestwick CTA 2')
kml_file.polyhedron(test_data.prestwick_cta_3, lower_layer=3000, upper_layer=5500, name='Prestwick CTA 3')
kml_file.polyhedron(test_data.prestwick_cta_4, lower_layer=3000, upper_layer=5500, name='Prestwick CTA 4')
kml_file.polyhedron(test_data.prestwick_cta_5, lower_layer=3500, upper_layer=5500, name='Prestwick CTA 5')
kml_file.polyhedron(test_data.prestwick_cta_6, lower_layer=4000, upper_layer=5500, name='Prestwick CTA 6')
kml_file.polyhedron(test_data.prestwick_ctr, upper_layer=5500, name='Prestwick CTR')
kml_file.polyhedron(test_data.test_airspace, upper_layer=50000, lower_layer=0, name='EG D406C ESKMEALS')
Acknowledgements
- Simplekml - for creating an awesome library which has helped me process_points many things and also inspiring me to write this library.`
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for KMLPlus-3.0.0b5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ac86f99bd3a465746aeac5ba9a7440d285e54d8db6fafb6c5d0a2c9d250604e4 |
|
MD5 | 1ef88fedf66c86842466f8912ad6ea54 |
|
BLAKE2b-256 | 9f321d2965ce118ad4c7fcde65456f2bced37e679fc7909f3afc375717e49762 |