Metadata-Version: 2.4
Name: kmlb
Version: 0.3.0
Summary: A straightforward Google Earth KML builder
Project-URL: Homepage, https://github.com/HFM3/kmlb
Project-URL: Documentation, https://kmlb.dev/
Project-URL: Repository, https://github.com/HFM3/kmlb
Project-URL: Issues, https://github.com/HFM3/kmlb/issues
Project-URL: Changelog, https://github.com/HFM3/kmlb/blob/main/pypi_package/CHANGELOG.md
Author: Henry F. Mros, III
License-Expression: MIT
License-File: LICENSE
Keywords: geospatial,gis,google-earth,keyhole,kml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/HFM3/kmlb/master/kmlb-docs/assets/kmlb-logo.png" alt="kmlb logo" width="230">
</p>

# KMLB

### Plain Python KML Builder.

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/kmlb.svg)](https://pypi.org/project/kmlb/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/HFM3/kmlb/blob/master/pypi_package/LICENSE)

KMLB is a dependency-free Python library for writing Google Earth KML files.
Easily create points, lines, polygons, styles, and folders.

Full documentation at [kmlb.dev](https://kmlb.dev/).

---

## Installation

```bash
pip install kmlb
```

Requires Python 3.9+. No third-party dependencies.

---

## Quick example

```python
import kmlb

# Define a reusable style and a styled point
style = kmlb.point_style("city", color=("#ff8800", 100), scale=1.4)
boston = kmlb.point([-71.0589, 42.3601], "Boston", style_to_use="city")

# Assemble a document and write it to disk
kmlb.kml("My Places", [boston], styles=[style], path="my_places.kml")
```

Open `my_places.kml` in [Google Earth](https://earth.google.com/) to view it.

---

<p align="center">
  <img src="https://raw.githubusercontent.com/HFM3/kmlb/master/kmlb-docs/assets/3D%20Buildings.jpg" alt="Orange wireframe building footprints extruded into 3D over Google Earth satellite imagery" width="900">
</p>

<p align="center"><sub>Building footprints extruded into 3D and viewed in Google Earth, built with kmlb polygons.</sub></p>

## Modules

| Module | Description |
|---|---|
| `kmlb` | Build points, POI/address searches, lines, polygons (with holes), point/line/polygon styles, folders, camera angles, and KML documents; geodesic `distance`, `bearing`, and `destination` |
| `kmlb.shapes` | Composite geometry: 2D shapes (`circle`, `ellipse`, `rectangle`, `ngon`, `annulus`, `arc`, `wedge`, `corridor`, `concentric_rings`, `grid`), 3D solids (`cylinder`, `cone`, `dome`, `sphere`), and `fresnel_zone` (RF link) |
| `kmlb.colors` / `kmlb.icons` | Named color presets and built-in marker shorthands for styling, so `color="red"` and `icon="triangle"` instead of hex tuples and full icon URLs |

The core builders are re-exported at the top level, so `kmlb.point(...)`,
`kmlb.kml(...)`, and friends work directly. See the
[reference](https://kmlb.dev/docs/reference/getting_started/) for every function.

<p align="center">
  <img src="https://raw.githubusercontent.com/HFM3/kmlb/master/kmlb-docs/assets/3D%20Shapes.jpg" alt="Colored 3D cylinder, cone, dome, and sphere volumes placed over Boston in Google Earth" width="900">
</p>

<p align="center"><sub>3D solids (cylinder, cone, dome, sphere) placed over Boston, built with <code>kmlb.shapes</code>.</sub></p>

---

## Example use

### Writing a basic KML file

```python
import kmlb

# CREATE A POINT
fountain = kmlb.point([-71.051904, 42.358988, 0], "Rings Fountain")

# WRITE KML FILE
kmlb.kml(
    "Boston Fountain",          # KML name
    [fountain],                 # Features
    path="folder/boston_fountain.kml"  # Export path
)
```

### Mapping a POI or an address

```python
import kmlb

# CREATE A POINT FROM A POI
bos_common = kmlb.search_poi("Boston Common, Boston, MA")

# CREATE A POINT FROM AN ADDRESS
ss = kmlb.search_poi("700 Atlantic Avenue, Boston, MA", name="South Station")

# WRITE KML FILE
kmlb.kml(
    "Boston Landmarks",          # KML name
    [bos_common, ss],            # Features
    path="folder/boston_landmarks.kml"  # Export path
)
```

### Creating a customized KML file

```python
import kmlb

# DEFINE A STYLE
pt_style = kmlb.point_style(
    "Red Triangle",                # Point style name
    icon="triangle",               # Icon (built-in shorthand)
    color=("#ff0000", 100),        # Icon color (hex, opacity)
    scale=1.0,                     # Icon scale
    label_color=("#ffffff", 100),  # Label color (hex, opacity)
    label_size=1.0,                # Label size
)

# CREATE A POINT
clock_tower = kmlb.point(
    [-71.053568, 42.359053, 151],                   # Coordinates
    "Custom House Tower",                           # Name
    headers=["City", "Building", "Height (M)"],     # Attribute titles
    attrs=["Boston", "Custom House Tower", "151"],  # Attributes
    z_mode="RTG",                                   # Relative To Ground
    style_to_use="Red Triangle",                    # Name of point style defined earlier
)

# WRITE KML FILE
kmlb.kml(
    "Boston Clock Tower",                     # KML name
    [clock_tower],                            # Features to include
    path="folder/boston_clock_tower.kml",     # Export path
    desc="Created with KMLB Python Package",  # KML description
    styles=[pt_style],                        # Styles to include
)
```

---

## Functions

| Function | What it does |
|---|---|
| **Features** | |
| `point` | Point placemark from a `[lon, lat]` (or `[lon, lat, elev]`) coordinate. |
| `search_poi` | Placemark located by an address or search string, geocoded by Google Earth. |
| `street_view` | Point placemark built from a Google Maps Street View URL that opens that panorama. |
| `line` | Line or polyline from an ordered list of coordinates. |
| `polygon` | Polygon from one or more rings (first ring outer, the rest holes). |
| **Styles** | |
| `point_style` | Reusable point style: icon, color, scale, and label. |
| `line_style` | Reusable line style: color and width. |
| `polygon_style` | Reusable polygon style: fill and outline. |
| **Geodesy (WGS-84)** | |
| `distance` | Distance in meters between two coordinates. |
| `bearing` | Initial bearing in degrees between two coordinates. |
| `destination` | Coordinate reached from an origin along a bearing and distance. |
| **Shapes** | |
| `shapes.circle` | Circle polygon of a given radius around a point. |
| `shapes.ellipse` | Ellipse polygon from two semi-axes and an orientation. |
| `shapes.rectangle` | Rectangle polygon centered on a point, rotatable. |
| `shapes.ngon` | Regular polygon (triangle, pentagon, hexagon, ...) around a point. |
| `shapes.annulus` | Filled ring polygon (an outer circle with a hole). |
| `shapes.arc` | Range-of-reach arc drawn as a line. |
| `shapes.wedge` | Pie-wedge (circular sector) polygon, useful for cellular coverage sectors. |
| `shapes.corridor` | Even-width buffered polygon around a path. |
| `shapes.concentric_rings` | Folder of range-ring outlines from a list or a start/interval/count series. |
| `shapes.grid` | Folder of square or hexagonal grid cells. |
| `shapes.fresnel_zone` | 3D Fresnel-zone tube plus line-of-sight path for a point-to-point radio link. |
| `shapes.cylinder` | 3D cylinder volume; orientable along any axis. |
| `shapes.cone` | 3D cone/beam; apex or base anchored, orientable along any axis. |
| `shapes.dome` | 3D hemisphere dome (or bowl when inverted). |
| `shapes.sphere` | 3D sphere; anchor by center or a pole. |
| **Views, documents, and links** | |
| `look_at` | Camera angle and view for a feature or document. |
| `camera` | Camera viewpoint (eye position and aim) for a feature or document. |
| `folder` | Group features and other folders together. |
| `kml` | Assemble features and styles into a KML document and write it to disk. |
| `networklink_kml` | Network-link KML that refreshes from a hosted URL. |
| **Color and icon helpers** | |
| `colors` | Named color palette (`colors.RED`, or `color="red"`). |
| `icons` | Built-in marker shorthands (`icon="triangle"`, `"red-paddle"`). |

<p align="center">
  <img src="https://raw.githubusercontent.com/HFM3/kmlb/master/kmlb-docs/assets/RF%20Scene.jpg" alt="A point-to-point Fresnel-zone tube and antenna coverage wedges drawn in 3D over Google Earth" width="900">
</p>

<p align="center"><sub>A Fresnel-zone link tube and antenna coverage wedges, built with <code>kmlb.shapes</code>.</sub></p>

---

## Citing KMLB

Using KMLB in research or published work? Citing is never required, but it's
always appreciated. Even a quick mention helps others discover KMLB and shows
where it's making a difference. APA, Chicago, and BibTeX formats, kept current
with each release, are at **[kmlb.dev/docs/cite](https://kmlb.dev/docs/cite/)**.

```bibtex
@software{KMLB,
  author  = {Mros, III, Henry F.},
  title   = {KMLB: KML Builder},
  year    = {2026},
  version = {0.3.0},
  url     = {https://pypi.org/project/kmlb/}
}
```

---

## License

[MIT](https://github.com/HFM3/kmlb/blob/master/pypi_package/LICENSE). Free to use, modify, and redistribute, including in commercial or
proprietary tools, as long as the copyright notice and license text are retained.
