@tmcw/togeojson 5.0.0-0 → 5.0.0-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
4
4
 
5
+ ## [5.0.0-1](https://github.com/placemarkio/togeojson/compare/v5.0.0-0...v5.0.0-1) (2022-03-14)
6
+
5
7
  ## [5.0.0-0](https://github.com/tmcw/togeojson/compare/v4.8.0-0...v5.0.0-0) (2022-03-14)
6
8
 
7
9
  ## [4.8.0-0](https://github.com/tmcw/togeojson/compare/v4.7.0...v4.8.0-0) (2022-03-14)
package/README.md CHANGED
@@ -10,6 +10,8 @@ to [GeoJSON](http://www.geojson.org/), in a browser or with [Node.js](http://nod
10
10
  - [x] Tested
11
11
  - [x] Node.js + Browsers
12
12
 
13
+ ## [📕 API Documentation](https://placemark.github.io/togeojson/)
14
+
13
15
  _This is a JavaScript library that lets projects convert KML and GPX to GeoJSON. If you're
14
16
  looking for a command line too, use [@tmcw/togeojson-cli](https://github.com/tmcw/togeojson-cli). If you
15
17
  want to convert one KML or GPX file, use [my online tool](https://observablehq.com/@tmcw/convert-kml-to-geojson).
package/dist/index.d.ts CHANGED
@@ -1,3 +1,95 @@
1
- export { gpx, gpxGen } from "./gpx";
2
- export { tcx, tcxGen } from "./tcx";
3
- export { kml, kmlWithFolders, kmlGen } from "./kml";
1
+ import { Feature, FeatureCollection, Geometry } from 'geojson';
2
+
3
+ /**
4
+ * Convert GPX to GeoJSON incrementally, returning
5
+ * a [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)
6
+ * that yields output feature by feature.
7
+ */
8
+ declare function gpxGen(node: Document): Generator<Feature>;
9
+ /**
10
+ *
11
+ * Convert a GPX document to GeoJSON. The first argument, `doc`, must be a GPX
12
+ * document as an XML DOM - not as a string. You can get this using jQuery's default
13
+ * `.ajax` function or using a bare XMLHttpRequest with the `.response` property
14
+ * holding an XML DOM.
15
+ *
16
+ * The output is a JavaScript object of GeoJSON data, same as `.kml` outputs, with the
17
+ * addition of a `_gpxType` property on each `LineString` feature that indicates whether
18
+ * the feature was encoded as a route (`rte`) or track (`trk`) in the GPX document.
19
+ */
20
+ declare function gpx(node: Document): FeatureCollection;
21
+
22
+ /**
23
+ * Incrementally convert a TCX document to GeoJSON. The
24
+ * first argument, `doc`, must be a TCX
25
+ * document as an XML DOM - not as a string.
26
+ */
27
+ declare function tcxGen(node: Document): Generator<Feature>;
28
+ /**
29
+ * Convert a TCX document to GeoJSON. The first argument, `doc`, must be a TCX
30
+ * document as an XML DOM - not as a string.
31
+ */
32
+ declare function tcx(node: Document): FeatureCollection;
33
+
34
+ declare type F = Feature<Geometry | null>;
35
+
36
+ interface Folder {
37
+ type: "folder";
38
+ meta: {
39
+ name?: string;
40
+ visibility?: string;
41
+ description?: string;
42
+ };
43
+ children: Array<Folder | F>;
44
+ }
45
+ /**
46
+ * A nested folder structure, represented
47
+ * as a tree with folders and features.
48
+ */
49
+ interface Root {
50
+ type: "root";
51
+ children: Array<Folder | F>;
52
+ }
53
+ /**
54
+ * Yield a nested tree with KML folder structure
55
+ *
56
+ * This generates a tree with the given structure:
57
+ *
58
+ * ```js
59
+ * {
60
+ * "type": "root",
61
+ * "children": [
62
+ * {
63
+ * "type": "folder",
64
+ * "meta": {
65
+ * "name": "Test"
66
+ * },
67
+ * "children": [
68
+ * // ...features and folders
69
+ * ]
70
+ * }
71
+ * // ...features
72
+ * ]
73
+ * }
74
+ * ```
75
+ */
76
+ declare function kmlWithFolders(node: Document): Root;
77
+ /**
78
+ * Convert KML to GeoJSON incrementally, returning
79
+ * a [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)
80
+ * that yields output feature by feature.
81
+ */
82
+ declare function kmlGen(node: Document): Generator<F>;
83
+ /**
84
+ * Convert a KML document to GeoJSON. The first argument, `doc`, must be a KML
85
+ * document as an XML DOM - not as a string. You can get this using jQuery's default
86
+ * `.ajax` function or using a bare XMLHttpRequest with the `.response` property
87
+ * holding an XML DOM.
88
+ *
89
+ * The output is a JavaScript object of GeoJSON data. You can convert it to a string
90
+ * with [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
91
+ * or use it directly in libraries.
92
+ */
93
+ declare function kml(node: Document): FeatureCollection<Geometry | null>;
94
+
95
+ export { gpx, gpxGen, kml, kmlGen, kmlWithFolders, tcx, tcxGen };
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sources":[],"sourcesContent":[],"names":[],"mappings":""}
@@ -15,7 +15,7 @@ function $ns(element, tagName, ns) {
15
15
  * get the content of a text node, if any
16
16
  */
17
17
  function nodeVal(node) {
18
- node === null || node === void 0 ? void 0 : node.normalize();
18
+ node?.normalize();
19
19
  return (node && node.textContent) || "";
20
20
  }
21
21
  /**
@@ -42,8 +42,8 @@ function get(node, tagName, callback) {
42
42
  function val1(node, tagName, callback) {
43
43
  const val = nodeVal(get1(node, tagName));
44
44
  if (val && callback)
45
- return callback(val);
46
- return val;
45
+ return callback(val) || {};
46
+ return {};
47
47
  }
48
48
  function $num(node, tagName, callback) {
49
49
  const val = parseFloat(nodeVal(get1(node, tagName)));
@@ -71,7 +71,7 @@ function getMulti(node, propertyNames) {
71
71
  return properties;
72
72
  }
73
73
  function isElement(node) {
74
- return (node === null || node === void 0 ? void 0 : node.nodeType) === 1;
74
+ return node?.nodeType === 1;
75
75
  }
76
76
 
77
77
  function getLineStyle(node) {
@@ -87,30 +87,52 @@ function getLineStyle(node) {
87
87
  return val;
88
88
  });
89
89
  }
90
+
90
91
  function getExtensions(node) {
91
92
  let values = [];
92
- if (node !== null) {
93
- for (const child of Array.from(node.childNodes)) {
94
- if (!isElement(child))
95
- continue;
96
- const name = ["heart", "gpxtpx:hr", "hr"].includes(child.nodeName)
97
- ? "heart"
98
- : child.nodeName;
99
- if (name === "gpxtpx:TrackPointExtension") {
100
- // loop again for nested garmin extensions (eg. "gpxtpx:hr")
101
- values = values.concat(getExtensions(child));
102
- }
103
- else {
104
- // push custom extension (eg. "power")
105
- const val = nodeVal(child);
106
- values.push([name, isNaN(parseFloat(val)) ? val : parseFloat(val)]);
107
- }
93
+ if (node === null)
94
+ return values;
95
+ for (const child of Array.from(node.childNodes)) {
96
+ if (!isElement(child))
97
+ continue;
98
+ const name = abbreviateName(child.nodeName);
99
+ if (name === "gpxtpx:TrackPointExtension") {
100
+ // loop again for nested garmin extensions (eg. "gpxtpx:hr")
101
+ values = values.concat(getExtensions(child));
102
+ }
103
+ else {
104
+ // push custom extension (eg. "power")
105
+ const val = nodeVal(child);
106
+ values.push([name, parseNumeric(val)]);
108
107
  }
109
108
  }
110
109
  return values;
111
110
  }
111
+ function abbreviateName(name) {
112
+ return ["heart", "gpxtpx:hr", "hr"].includes(name) ? "heart" : name;
113
+ }
114
+ function parseNumeric(val) {
115
+ const num = parseFloat(val);
116
+ return isNaN(num) ? val : num;
117
+ }
118
+
119
+ function coordPair$1(node) {
120
+ const ll = [
121
+ parseFloat(node.getAttribute("lon") || ""),
122
+ parseFloat(node.getAttribute("lat") || ""),
123
+ ];
124
+ num1(node, "ele", (val) => {
125
+ ll.push(val);
126
+ });
127
+ const time = get1(node, "time");
128
+ return {
129
+ coordinates: ll,
130
+ time: time ? nodeVal(time) : null,
131
+ extendedValues: getExtensions(get1(node, "extensions")),
132
+ };
133
+ }
134
+
112
135
  function extractProperties(node) {
113
- var _a;
114
136
  const properties = getMulti(node, [
115
137
  "name",
116
138
  "cmt",
@@ -121,7 +143,7 @@ function extractProperties(node) {
121
143
  ]);
122
144
  const extensions = Array.from(node.getElementsByTagNameNS("http://www.garmin.com/xmlschemas/GpxExtensions/v3", "*"));
123
145
  for (const child of extensions) {
124
- if (((_a = child.parentNode) === null || _a === void 0 ? void 0 : _a.parentNode) === node) {
146
+ if (child.parentNode?.parentNode === node) {
125
147
  properties[child.tagName.replace(":", "_")] = nodeVal(child);
126
148
  }
127
149
  }
@@ -131,6 +153,7 @@ function extractProperties(node) {
131
153
  }
132
154
  return properties;
133
155
  }
156
+
134
157
  function getPoints$1(node, pointname) {
135
158
  const pts = $(node, pointname);
136
159
  if (pts.length < 2)
@@ -157,21 +180,6 @@ function getPoints$1(node, pointname) {
157
180
  extendedValues: extendedValues,
158
181
  };
159
182
  }
160
- function coordPair$1(node) {
161
- const ll = [
162
- parseFloat(node.getAttribute("lon") || ""),
163
- parseFloat(node.getAttribute("lat") || ""),
164
- ];
165
- num1(node, "ele", (val) => {
166
- ll.push(val);
167
- });
168
- const time = get1(node, "time");
169
- return {
170
- coordinates: ll,
171
- time: time ? nodeVal(time) : null,
172
- extendedValues: getExtensions(get1(node, "extensions")),
173
- };
174
- }
175
183
  function getRoute(node) {
176
184
  const line = getPoints$1(node, "rtept");
177
185
  if (!line)
@@ -253,6 +261,11 @@ function getPoint(node) {
253
261
  },
254
262
  };
255
263
  }
264
+ /**
265
+ * Convert GPX to GeoJSON incrementally, returning
266
+ * a [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)
267
+ * that yields output feature by feature.
268
+ */
256
269
  function* gpxGen(node) {
257
270
  for (const track of $(node, "trk")) {
258
271
  const feature = getTrack(track);
@@ -268,6 +281,17 @@ function* gpxGen(node) {
268
281
  yield getPoint(waypoint);
269
282
  }
270
283
  }
284
+ /**
285
+ *
286
+ * Convert a GPX document to GeoJSON. The first argument, `doc`, must be a GPX
287
+ * document as an XML DOM - not as a string. You can get this using jQuery's default
288
+ * `.ajax` function or using a bare XMLHttpRequest with the `.response` property
289
+ * holding an XML DOM.
290
+ *
291
+ * The output is a JavaScript object of GeoJSON data, same as `.kml` outputs, with the
292
+ * addition of a `_gpxType` property on each `LineString` feature that indicates whether
293
+ * the feature was encoded as a route (`rte`) or track (`trk`) in the GPX document.
294
+ */
271
295
  function gpx(node) {
272
296
  return {
273
297
  type: "FeatureCollection",
@@ -430,6 +454,11 @@ function getLap(node) {
430
454
  },
431
455
  };
432
456
  }
457
+ /**
458
+ * Incrementally convert a TCX document to GeoJSON. The
459
+ * first argument, `doc`, must be a TCX
460
+ * document as an XML DOM - not as a string.
461
+ */
433
462
  function* tcxGen(node) {
434
463
  for (const lap of $(node, "Lap")) {
435
464
  const feature = getLap(lap);
@@ -442,6 +471,10 @@ function* tcxGen(node) {
442
471
  yield feature;
443
472
  }
444
473
  }
474
+ /**
475
+ * Convert a TCX document to GeoJSON. The first argument, `doc`, must be a TCX
476
+ * document as an XML DOM - not as a string.
477
+ */
445
478
  function tcx(node) {
446
479
  return {
447
480
  type: "FeatureCollection",
@@ -633,10 +666,12 @@ function getGeometry(node) {
633
666
  coords.push(ring);
634
667
  }
635
668
  }
636
- geometries.push({
637
- type: "Polygon",
638
- coordinates: coords,
639
- });
669
+ if (coords.length) {
670
+ geometries.push({
671
+ type: "Polygon",
672
+ coordinates: coords,
673
+ });
674
+ }
640
675
  break;
641
676
  }
642
677
  case "Track":
@@ -670,38 +705,55 @@ function extractExtendedData(node) {
670
705
  return properties;
671
706
  });
672
707
  }
708
+ function geometryListToGeometry(geometries) {
709
+ return geometries.length === 0
710
+ ? null
711
+ : geometries.length === 1
712
+ ? geometries[0]
713
+ : {
714
+ type: "GeometryCollection",
715
+ geometries,
716
+ };
717
+ }
718
+ function extractTimeSpan(node) {
719
+ return get(node, "TimeSpan", (timeSpan) => {
720
+ return {
721
+ timespan: {
722
+ begin: nodeVal(get1(timeSpan, "begin")),
723
+ end: nodeVal(get1(timeSpan, "end")),
724
+ },
725
+ };
726
+ });
727
+ }
728
+ function extractTimeStamp(node) {
729
+ return get(node, "TimeStamp", (timeStamp) => {
730
+ return { timestamp: nodeVal(get1(timeStamp, "when")) };
731
+ });
732
+ }
733
+ function extractCascadedStyle(node, styleMap) {
734
+ return val1(node, "styleUrl", (styleUrl) => {
735
+ styleUrl = normalizeId(styleUrl);
736
+ if (styleMap[styleUrl]) {
737
+ return Object.assign({ styleUrl }, styleMap[styleUrl]);
738
+ }
739
+ // For backward-compatibility. Should we still include
740
+ // styleUrl even if it's not resolved?
741
+ return { styleUrl };
742
+ });
743
+ }
673
744
  function getPlacemark(node, styleMap) {
674
745
  const { coordTimes, geometries } = getGeometry(node);
675
746
  const feature = {
676
747
  type: "Feature",
677
- geometry: geometries.length === 0
678
- ? null
679
- : geometries.length === 1
680
- ? geometries[0]
681
- : {
682
- type: "GeometryCollection",
683
- geometries,
684
- },
685
- properties: Object.assign(getMulti(node, ["name", "address", "visibility", "description"]), val1(node, "styleUrl", (styleUrl) => {
686
- styleUrl = normalizeId(styleUrl);
687
- if (styleMap[styleUrl]) {
688
- return Object.assign({ styleUrl }, styleMap[styleUrl]);
689
- }
690
- else {
691
- // For backward-compatibility. Should we still include
692
- // styleUrl even if it's not resolved?
693
- return { styleUrl };
694
- }
695
- }), extractStyle(node), extractExtendedData(node), get(node, "TimeSpan", (timeSpan) => {
696
- return {
697
- timespan: {
698
- begin: nodeVal(get1(timeSpan, "begin")),
699
- end: nodeVal(get1(timeSpan, "end")),
700
- },
701
- };
702
- }), get(node, "TimeStamp", (timeStamp) => {
703
- return { timestamp: nodeVal(get1(timeStamp, "when")) };
704
- }), coordTimes.length
748
+ geometry: geometryListToGeometry(geometries),
749
+ properties: Object.assign(getMulti(node, [
750
+ "name",
751
+ "address",
752
+ "visibility",
753
+ "open",
754
+ "phoneNumber",
755
+ "description",
756
+ ]), extractCascadedStyle(node, styleMap), extractStyle(node), extractExtendedData(node), extractTimeSpan(node), extractTimeStamp(node), coordTimes.length
705
757
  ? {
706
758
  coordinateProperties: {
707
759
  times: coordTimes.length === 1 ? coordTimes[0] : coordTimes,
@@ -742,7 +794,15 @@ function buildStyleMap(node) {
742
794
  return styleMap;
743
795
  }
744
796
  function getFolder(node) {
745
- const props = ["name", "visibility", "description"];
797
+ const props = [
798
+ "name",
799
+ "visibility",
800
+ "open",
801
+ "address",
802
+ "description",
803
+ "phoneNumber",
804
+ "visibility",
805
+ ];
746
806
  const meta = {};
747
807
  for (const child of Array.from(node.childNodes)) {
748
808
  if (isElement(child) && props.includes(child.tagName)) {
@@ -757,6 +817,26 @@ function getFolder(node) {
757
817
  }
758
818
  /**
759
819
  * Yield a nested tree with KML folder structure
820
+ *
821
+ * This generates a tree with the given structure:
822
+ *
823
+ * ```js
824
+ * {
825
+ * "type": "root",
826
+ * "children": [
827
+ * {
828
+ * "type": "folder",
829
+ * "meta": {
830
+ * "name": "Test"
831
+ * },
832
+ * "children": [
833
+ * // ...features and folders
834
+ * ]
835
+ * }
836
+ * // ...features
837
+ * ]
838
+ * }
839
+ * ```
760
840
  */
761
841
  function kmlWithFolders(node) {
762
842
  const styleMap = buildStyleMap(node);
@@ -789,8 +869,9 @@ function kmlWithFolders(node) {
789
869
  return tree;
790
870
  }
791
871
  /**
792
- * Yield features, one by one. Does not include
793
- * or care for folders.
872
+ * Convert KML to GeoJSON incrementally, returning
873
+ * a [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)
874
+ * that yields output feature by feature.
794
875
  */
795
876
  function* kmlGen(node) {
796
877
  const styleMap = buildStyleMap(node);
@@ -800,6 +881,16 @@ function* kmlGen(node) {
800
881
  yield feature;
801
882
  }
802
883
  }
884
+ /**
885
+ * Convert a KML document to GeoJSON. The first argument, `doc`, must be a KML
886
+ * document as an XML DOM - not as a string. You can get this using jQuery's default
887
+ * `.ajax` function or using a bare XMLHttpRequest with the `.response` property
888
+ * holding an XML DOM.
889
+ *
890
+ * The output is a JavaScript object of GeoJSON data. You can convert it to a string
891
+ * with [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
892
+ * or use it directly in libraries.
893
+ */
803
894
  function kml(node) {
804
895
  return {
805
896
  type: "FeatureCollection",