Pages on ikml.com

About

Mon, 01 Jan 0001 00:00:00 +0000

ikml.com is the home of iKML, a small tool that helps you understand a geographic file before you import it. It reads KML, KMZ and GeoJSON, shows what’s inside, flags what’s broken, tells you what a conversion to another format will lose, and writes a cleaned copy with a list of every change.

Why It Exists

Map files get passed around more than almost any other kind of data. A drone pilot sends a mission KMZ, a surveyor sends site boundaries, a council publishes a layer, a colleague exports a Google My Maps project. The person receiving it opens it in QGIS, ArcGIS, a web map or a spreadsheet, and that’s where things go wrong without a word: points in the ocean, polygons that don’t draw, icons missing, attribute data and folders gone after a conversion.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

ikml.com would like to hear from:

Anyone checking real files with iKML. What it found, what it missed, and which tool the file came from.
Anyone who found a bug. A good file iKML called broken, a broken one it passed, a conversion that lost something the report didn’t mention.
Anyone with an idea for a format, a check or an exporter quirk iKML should know about.

Write to info@ikml.com.

Download iKML

Mon, 01 Jan 0001 00:00:00 +0000

The ikml command is one file with nothing else to install. Each archive below holds it with its license files. The links always point to the latest release.

System	Download
Linux, x86-64	ikml_linux_amd64.tar.gz
Linux, ARM64	ikml_linux_arm64.tar.gz
macOS, Apple silicon	ikml_darwin_arm64.tar.gz
macOS, Intel	ikml_darwin_amd64.tar.gz
Windows, x86-64	ikml_windows_amd64.zip

Checksums are in SHA256SUMS. Every release is listed on GitHub.

Install

On Linux or macOS:

tar -xzf ikml_linux_amd64.tar.gz
sudo mv ikml /usr/local/bin/
ikml version

The binaries are static, so they run on any Linux distribution. The macOS binaries aren’t signed by Apple, so macOS may block the first run; allow it in System Settings under Privacy & Security, or run xattr -d com.apple.quarantine ikml. On Windows, unzip the archive and put ikml.exe in a folder on your PATH.

Inspector

Mon, 01 Jan 0001 00:00:00 +0000

Drop a KML, KMZ or GeoJSON file below. iKML reads it inside this page and shows what’s in it, what’s broken and what a conversion would lose. You can download a cleaned copy as GeoJSON, KML or KMZ.

Your File Stays Here

The inspector is iKML’s engine compiled to WebAssembly. Your browser reads the file from your disk and hands it to that engine in memory. Nothing is uploaded, and the page makes no other network requests once it has loaded. The preview is drawn from the coordinates alone, without map tiles, so not even the area you’re looking at is sent anywhere.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

The fastest start is no install at all: drop a file on the inspector. This page covers the ikml program, for batches of files, scripts and data pipelines.

1. Get the ikml Command

Download the archive for your system from the download page, unpack it and put ikml somewhere on your PATH. Check it works:

ikml version

2. See What’s Inside

ikml inspect reads KML, KMZ and GeoJSON, whatever the file is called, and shows its structure, its attribute fields and styles, and anything worth knowing:

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Every issue iKML reports has a stable code. Scripts can match on the codes; they don’t change between versions. The same list is in the program: ikml codes.

Severity decides the exit code of ikml check: errors give exit status 1, warnings give 1 only with --strict, and info never does.

Errors

Code	Meaning	What `ikml clean` does
`xml-invalid`	The KML is not well-formed XML. Most programs refuse the whole file. iKML reports the line and keeps what it could read before the problem.	Reported, not changed.
`json-invalid`	The GeoJSON is not valid JSON. iKML reports the line of the first problem.	Reported, not changed.
`geojson-structure`	The JSON is valid but does not follow GeoJSON rules, for example a missing “type” or a position that is not an array of numbers.	Reported, not changed.
`kmz-invalid`	The file starts like a zip archive but cannot be read as one.	Reported, not changed.
`kmz-no-kml`	The KMZ archive has no .kml file inside, so there is nothing to show.	Reported, not changed.
`kmz-too-large`	The KMZ expands past iKML’s safety limit (512 MiB in total, or an entry that compresses far better than real data does). iKML stops reading to protect your machine.	Reported, not changed.
`coord-parse`	A coordinate tuple could not be read as two or three numbers. Viewers usually drop the point or the whole shape.	Not fixed. The tuple is left as it is in KML output and dropped from GeoJSON output.
`lon-range`	A longitude is outside -180 to 180.	Reported, not changed.
`lat-range`	A latitude is outside -90 to 90.	Reported, not changed.
`swapped-latlon`	Every point of a placemark has the first value inside ±90 and the second outside ±90. That can only happen when latitude and longitude were written in the wrong order.	Fixed only with –fix-swapped.
`ring-unclosed`	A polygon ring does not end on its first point. KML and GeoJSON both require closed rings.	Fixed: the first point is appended.
`ring-too-short`	A polygon ring has fewer than 4 positions (3 corners plus the closing point), so it has no area.	Reported, not changed.
`line-too-short`	A line has fewer than 2 positions.	Reported, not changed.
`polygon-no-outer`	A Polygon has no outer boundary.	Reported, not changed.
`kmz-missing-asset`	The document refers to a file (icon, image, overlay, model) that should be inside the KMZ but is not there.	Reported, not changed.
`local-path-ref`	A reference points to a file on the creator’s computer (file:///, C:, /Users/, /home/ and similar). Nobody else can open it.	Reported, not changed.
`kmz-unsafe-path`	A file inside the KMZ has a name that would unpack outside the folder: an absolute path, a drive letter or a .. step. A KMZ from a real mapping program never has one, and some unzip tools would write the file wherever the name points.	Fixed: the entry is left out of the cleaned copy, and iKML never writes such a name.
`style-missing`	A placemark uses a style (#id) that is not defined in the document. Viewers fall back to default styling.	Fixed: the broken styleUrl is removed.

Warnings

Code	Meaning	What `ikml clean` does
`null-island`	A position is exactly 0,0, in the Gulf of Guinea. This is usually a missing value written as zero.	Reported, not changed.
`duplicate-points`	A line or ring repeats the same position twice in a row.	Fixed: repeats are removed, as long as the shape keeps enough points. GPS tracks are left alone.
`coord-spacing`	Coordinates have spaces next to the commas (“34.8, 32.1”). KML separates points with spaces, so some programs read each number as its own point.	Fixed: the coordinates are rewritten without the extra spaces.
`empty-placemark`	A placemark or feature has no geometry, so it will not show on a map.	Kept and reported.
`http-ref`	A reference uses plain http://. Browsers and some viewers block it, and the content is not inside the file.	Reported, not changed.
`mixed-dimensions`	One shape mixes 2D (lon,lat) and 3D (lon,lat,alt) positions.	Reported, not changed.
`geojson-crs`	The GeoJSON has a “crs” member. RFC 7946 removed it, and most tools ignore it and assume WGS 84 degrees.	Fixed when the crs names WGS 84 (CRS84 or EPSG:4326): the member is removed. Other systems are left, because the coordinates would need reprojecting.
`geojson-nested-collection`	A GeometryCollection contains another GeometryCollection. RFC 7946 says not to do this and many tools reject it.	Reported, not changed.
`old-namespace`	The file uses the KML 2.0 or 2.1 namespace. Newer tools expect 2.2.	Fixed: the namespace is changed to KML 2.2.
`no-kml-root`	The XML root is a Document, Folder or Placemark without the `<kml>` wrapper.	Reported, not changed.
`altitude-ignored`	Positions have non-zero altitudes but the altitude mode is clampToGround (the default). Most viewers will draw them on the ground.	Reported, not changed.
`large-coordinate-count`	One placemark has more than 100,000 positions. Many web maps slow down or refuse shapes this large.	Reported, not changed.
`track-times-mismatch`	A gx:Track has a different number of `<when>` times and `<gx:coord>` positions. KML requires one time per position.	Reported, not changed.
`kmz-duplicate-entry`	The KMZ holds two files with the same name. Programs differ on which one they use.	Fixed: the first copy is kept.
`duplicate-ids`	Two elements share the same id. Style references and feature lookups may pick the wrong one.	Reported, not changed.

Info

Code	Meaning	What `ikml clean` does
`no-namespace`	The `<kml>` root has no namespace. Most programs read it anyway.	Fixed: the KML 2.2 namespace is added.
`remote-ref`	A reference points to an https:// address. It works online but the content is not inside the file.	Reported, not changed.
`external-file-ref`	A plain .kml file refers to a file next to it on disk (for example an icon). That file must travel with the .kml.	Reported, not changed.
`network-link`	The file contains a NetworkLink. Its contents load from elsewhere and are not part of this file.	Reported, not changed.
`unused-asset`	A file inside the KMZ is not referenced by the document.	Removed only with –drop-unused.
`unknown-element`	An element iKML does not interpret, such as a vendor extension. It is kept in KML output and dropped from GeoJSON output.	Reported, not changed.
`winding`	A GeoJSON ring winds the opposite way from RFC 7946 (outer rings counterclockwise, holes clockwise). Most tools accept either.	Fixed in GeoJSON output: rings are rewound.
`foreign-members`	The GeoJSON has members outside the specification. They are kept in GeoJSON output and dropped from KML output.	Reported, not changed.
`overlay-present`	The file contains image overlays (GroundOverlay, ScreenOverlay or PhotoOverlay).	Reported, not changed.
`model-present`	The file contains 3D models.	Reported, not changed.
`has-tracks`	The file contains gx:Track GPS tracks with a time for each point.	Reported, not changed.
`has-timestamps`	Placemarks carry TimeStamp or TimeSpan values.	Reported, not changed.
`empty-folder`	A Folder or Document has nothing inside.	Reported, not changed.
`encoding-converted`	The file is not UTF-8. iKML converted it, and cleaned output is written as UTF-8.	Reported, not changed.

What a conversion loses

ikml convert and ikml convert --report print a loss report for the file in hand. For KML to GeoJSON, these are the parts it covers: