Parsing and conversion to DataFrame performance enhancement

Project.toml

@@ -4,19 +4,42 @@ authors = ["Josh Day <[email protected]> and contributors"]
 version = "0.2.5"
 
 [deps]
-GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
+Automa = "67c07d97-cdcb-5c2c-af73-a7f9c32a568b"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
+Parsers = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
+REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+Scratch = "6c6a2e73-6563-6170-7368-637461726353"
+Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
+TimeZones = "f269a46b-ccf7-5d73-abea-4c690281aa53"
 XML = "72c71f33-b9b6-44de-8c94-c961784809e2"
 
+[weakdeps]
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+ZipArchives = "49080126-0e18-4c2a-b176-c102e4b3760c"
+
+[extensions]
+KMLDataFramesExt = "DataFrames"
+KMLGeoInterfaceExt = "GeoInterface"
+KMLMakieExt = "Makie"
+KMLZipArchivesExt = "ZipArchives"
+
 [compat]
+Automa = "1.1"
 GeoInterface = "1.3"
+JSON3 = "1.14"
 OrderedCollections = "1"
-XML = "0.3.0"
-julia = "1"
-
-[extras]
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-
-[targets]
-test = ["Test"]
+Parsers = "2.8"
+Scratch = "1.2"
+StaticArrays = "1.9"
+Tables = "1.12"
+TimeZones = "1.21"
+XML = "0.3"
+julia = "1.10"

ext/KMLDataFramesExt.jl

@@ -0,0 +1,85 @@
+# ext/KMLDataFramesExt.jl
+
+module KMLDataFramesExt
+
+using DataFrames
+import KML
+import KML: KMLFile, LazyKMLFile, PlacemarkTable, read
+
+
+"""
+    DataFrame(kml_file::Union{KML.KMLFile,KML.LazyKMLFile}; layer::Union{Nothing,String,Integer}=nothing, simplify_single_parts::Bool=false)
+
+Constructs a DataFrame from the Placemarks in a `KMLFile` or `LazyKMLFile` object.
+
+# Arguments
+
+  - `kml_file::Union{KML.KMLFile,KML.LazyKMLFile}`: The KML file object already read into memory.
+    LazyKMLFile is more efficient for this use case as it doesn't materialize the entire KML structure.
+
+  - `layer::Union{Nothing,String,Integer}=nothing`: Specifies the layer to extract Placemarks from.
+
+      + If `nothing` (default): The behavior is defined by `KML.PlacemarkTable` (e.g., attempts to find a default layer or prompts if multiple are available and in interactive mode).
+      + If `String`: The name of the Document or Folder to use as the layer.
+      + If `Integer`: The index of the layer to use.
+  - `simplify_single_parts::Bool=false`: If `true`, when a MultiGeometry contains only a single geometry part, that part is extracted directly, simplifying the structure. For example, a MultiGeometry containing a single LineString will be treated as a LineString. Defaults to `false`.
+"""
+function DataFrames.DataFrame(
+    kml_file::Union{KML.KMLFile,KML.LazyKMLFile};
+    layer::Union{Nothing,String,Integer} = nothing,
+    simplify_single_parts::Bool = false,
+)
+    placemark_table = KML.PlacemarkTable(kml_file; layer = layer, simplify_single_parts = simplify_single_parts)
+    return DataFrames.DataFrame(placemark_table)
+end
+
+"""
+    DataFrame(kml_path::AbstractString; layer::Union{Nothing,String,Integer}=nothing, simplify_single_parts::Bool=false, lazy::Bool=true)
+
+Constructs a DataFrame from the Placemarks in a KML file specified by its path.
+
+# Arguments
+
+  - `kml_path::AbstractString`: Path to the .kml or .kmz file.
+
+  - `layer::Union{Nothing,String,Integer}=nothing`: Specifies the layer to extract Placemarks from.
+
+      + If `nothing` (default): The behavior is defined by `KML.PlacemarkTable` (e.g., attempts to find a default layer or prompts if multiple are available and in interactive mode).
+      + If `String`: The name of the Document or Folder to use as the layer.
+      + If `Integer`: The index of the layer to use.
+  - `simplify_single_parts::Bool=false`: If `true`, when a MultiGeometry contains only a single geometry part, it will be simplified to that single geometry. For example, a MultiGeometry containing a single Point will become just a Point. Defaults to `false`.
+  - `lazy::Bool=true`: If `true` (default), uses `LazyKMLFile` for better performance when only extracting placemarks.
+    If `false`, uses regular `KMLFile` which materializes the entire KML structure.
+    For DataFrame extraction, `lazy=true` is recommended as it's significantly faster for large files.
+
+# Examples
+
+```julia
+# Default lazy loading (recommended for DataFrames)
+df = DataFrame("large_file.kml")
+
+# Force eager loading if you need the full KML structure later
+df = DataFrame("file.kml"; lazy = false)
+
+# Select a specific layer by name
+df = DataFrame("file.kml"; layer = "Points of Interest")
+
+# Select layer by index
+df = DataFrame("file.kml"; layer = 2)
+```
+"""
+function DataFrames.DataFrame(
+    kml_path::AbstractString;
+    layer::Union{Nothing,String,Integer} = nothing,
+    simplify_single_parts::Bool = false,
+    lazy::Bool = true,
+)
+    kml_file_obj = if lazy
+        KML.read(kml_path, KML.LazyKMLFile)
+    else
+        KML.read(kml_path, KML.KMLFile)
+    end
+    return DataFrames.DataFrame(kml_file_obj; layer = layer, simplify_single_parts = simplify_single_parts)
+end
+
+end # module KMLDataFramesExt