Prepare for 0.0.6 (#81)

* initial null-safety implementation * attributes non-nullable + tests, fix meta tests * make altitude for Position and BBox nullable * update action deps, build runner * delete conflicting outputs, dart test on PR action * Strongly type and refactor geomEach meta function This commit also renames Geometry to GeometryObject * simplify geomEach * Add coverage reporting to pull requests tests * Allow PR coverage comment to fail This allows PRs from forks to still run the tests successfully * Refactor coverage reporting into its own job The coverage job is allowed to continue on error, letting the entire workflow 'pass' if we hit issues running or reporting coverage * Move coverage reporting into separate workflow * geomEach: nullable fields #36 * fix types in tests * Update to latest romeovs/lcov-reporter-action This should resolve an issue where the 'comment code coverage on PR' action fails after being merged into main. See romeovs/lcov-reporter-action#16 * raise version for release 0.0.3 * [meta] add implementation and test for featureEach and propEach (#24) * Assemble different types, refactor GeoJSON serialization, general improvements (#43) * #19, #20, #21, refactor * convert GeoJSONObjectType to enum, rename * rm overridden bboxes * Implement vector operations #23 * statically type 'round' helper func, fix unit test * gen coverage * fix typo * geojson unit tests, type fixes * fix deserialization with GeoJSONObjectType, implement hashCode * initial unit tests for new constructors * integration tests * fix path * test bbox on other geojson types * update enum tests * required params for new constructors, unit tests * license notices * bump version for release * Add basic benchmarking framework (#51) * Add pub version badge * [meta] add coordeach implementation (#50) * [meta] add coordeach implementation * [benchmark] add coordeach benchmark using test fixtures * Add implementation for getCoord & getCoords // invariant package (#53) * initial getCoord & getCoords implementation * WIP test coords/coord * test gitpod flutter config * ports invariants package (#62) * dart pub get added * wip, type problem * fixed return error of the test * Gitpod config * new test cases, changed comments * standardized the comments * wrapped List in brackets * some minor typo edit * added highlight in documentation * formatted conflicting files * deleted the gitpod files Co-authored-by: Arman Torkzaban <[email protected]> Co-authored-by: arman <[email protected]> Co-authored-by: arman <[email protected]> Co-authored-by: Arman Torkzaban <[email protected]> * Add flattenEach function and tests (#48) * Add flattenEach function and tests * Refactor flattenEach slightly * Refactor meta -- breaking of iterations tests * Explicitly do not support nested GeometryCollections * Update documentation links * Use more specific type checks in flattenEach test * rm duplicate fcMixed * remove geometryCollection clause * warning for nested GeometryCollection Co-authored-by: Lukas Himsel <[email protected]> * refactor coordEach with geomEach, change type in geomEach callback (#68) * [meta] add coordeach implementation * Rework coordEach implementation to match setup more from geomEach * cleanup * optimize for geometry collection * refactor coordEach with geomEach, change type in geomEach callback Co-authored-by: Tobrun Van Nuland <[email protected]> * Port coordAll function and test, also: refactor coordEach callback (#64) * beginning * wip coordAll * coordAll test, WIP * changes CoordEachCallback's signature * typecast removed, test corrected * changes before merging * refactor for Position in CoordEachCallback Co-authored-by: Lukas Himsel <[email protected]> * Update README.md * Feature reducers (#49) * Temporarily type geomEach callback to GeometryType * Add geomReduce function and tests * propReduce function * WIP - featureReduce() * WIP * added examples and documentations * flattenReduce WIP * WIP * coordReduce * documentation * add static types * merge readme * prepare new merge * generic types for all reducer functions * TurfJS compatible solution with type checks * add cloning * fixed types passed to callbacks, propReduce test * flattenReduce and featureReduce test * coordReduce * minor type conv. num to int Co-authored-by: Arman Torkzaban <[email protected]> Co-authored-by: Lukas Himsel <[email protected]> * Port cluster functions and tests (#69) * port functions * getCluster documentation * WIP documentation * Did the documentation * wrote tests * benchmarks - in process * moved benchmarks to separate file * exported clusters.dart Co-authored-by: armantorkzaban <[email protected]> * Port meta segment functions & lineSegment (#70) * initial commit to segment file * beginning * lineSegment() * lineSegment * refactor * lineSegment tests * polygon test * wip segmentEach * rewrite segmentEach witohut coordEach * fix flattenEachCallback * combine units * tests for segmentEach * segmentEach id check tests * segmentReduce impltd. * updated README * Documentation * benchmark init Co-authored-by: Arman Torkzaban <[email protected]> * split up meta into separate files (#72) * Meta functions extension methods (#73) * initial setup * fix export, add all *each functions * implement 'other' functions * implement *reduce functions * fix tests * rm geojson param for reducers * Update functions and packages in README.md (#67) * WIP - updating README.md * missing new functions & packages * helpers function aint needed anymore - constructor * Links added and unnecessary funtioncs deleted Co-authored-by: Lukas Himsel <[email protected]> * Raise version to 0.0.5 * Documentation (#75) * in process - early analysis of the work * linked the meta functions in readme * CONTRIBUTING.md * links to the sources * edited typos * documentation work * closes #77, closes #16 * proofread * improves pub.dev score, closes #79, #78, #75 * Added deleted model, complemented contributing.md Co-authored-by: Lukas Himsel <[email protected]> * raise to version 0.0.6 Co-authored-by: Brad Parham <[email protected]> Co-authored-by: Tobrun <[email protected]> Co-authored-by: arman <[email protected]> Co-authored-by: arman <[email protected]> Co-authored-by: Arman Torkzaban <[email protected]>
dartclub · Apr 19, 2022 · 0ddf01e · 0ddf01e
1 parent 6a36cb4
commit 0ddf01e
Show file tree

Hide file tree

Showing 17 changed files with 404 additions and 211 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,10 @@
+## 0.0.6
+
+- This is solely a quality release, without new functionality:
+- Documentation: improves pub.dev scores, raised documentation coverage, fixed typos
+- Return type fixes for the the meta extensions
+
+
 ## 0.0.5
 
 - Implements *all* meta functions and`lineSegment` 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,94 @@
+# Contributiung to Turf.dart
+
+Welcome and thank you for deciding to contribute to the project!
+
+Here is how cooperation works perfectly at [Turf Dart](https://github.com/dartclub/turf_dart)
+#### Table of Contents
+  - [Code of Conduct](#code-of-conduct)
+  - [Get started](#get-started)
+  - [Structure of modules](#structure-of-modules)
+  - [Implementation Process](#implementation-process)
+  - [Documentation](#documentation)
+  - [GeoJSON object model](#GeoJSON-object-model)
+
+## Code of conduct
+By participating, you are expected to uphold international human rights and fundamental freedoms!
+To put it simply, be kind to each other. 
+
+## Get started
+- Get the [Dart tools](https://dart.dev/tools)
+- Clone the repository: ```git clone [email protected]:dartclub/turf_dart.git```
+- Navigate to project's folder in terminal & get its dependencies:  ```dart pub get```
+- Go through [Implementation Process](#implementation-process)
+- Import the library in your code and use it. For example:
+```dart
+import 'package:turf/helpers.dart';
+import 'package:turf/src/line_segment.dart';
+
+  Feature<Polygon> poly = Feature<Polygon>(
+    geometry: Polygon(coordinates: [
+      [
+        Position(0, 0),
+        Position(2, 2),
+        Position(0, 1),
+        Position(0, 0),
+      ],
+      [
+        Position(0, 0),
+        Position(1, 1),
+        Position(0, 1),
+        Position(0, 0),
+      ],
+    ]),
+  );
+
+var total = segmentReduce<int>(poly, (previousValue,
+        currentSegment,
+        initialValue,
+        featureIndex,
+        multiFeatureIndex,
+        geometryIndex,
+        segmentIndex) {
+      if (previousValue != null) {
+        previousValue++;
+      }
+      return previousValue;
+    }, 0, combineNestedGeometries: false);
+// total.length ==  6
+```
+## Structure of modules
+```
+TURF_DART/lib/<MODULE NAME>.dart // public facing API, exports the implementation
+         │   │
+         │   └───src/<MODULE NAME>.dart // the implementation
+         │ 
+         └───benchmark/<MODULE NAME>_benchmark.dart
+         │
+         └───test/components/<MODULE NAME>_test.dart // all the related tests
+```
+## Implementation process
+- Check the Backlog/Issues for similar issues
+- Create a new branch _feature-_ from _main_
+- Create a _draft Pull request_, mention in it the associated issues
+- **Implement**
+  - Document everything [properly](#documentation)
+  - If you are importing tests, comments etc. from [Turfjs](https://github.com/Turfjs/turf), please make sure you refactor it so it conforms with Dart syntax.
+  - **Write [tests](https://dart.dev/guides/testing)**―Keep an eye on [Turfjs'](https://github.com/Turfjs/turf) implementation
+    - run the the test: ```dart test test/components/XXX.dart```
+  - **Write [benchmarks](https://pub.dev/packages/benchmark)**―have a look at our [implementation](https://github.com/dartclub/turf_dart/tree/main/benchmark)
+    - run the benchmark: ```dart pub run benchmark```
+- Commit
+- Convert to real Pull request _ready for review_
+- Code review / mention a reviewer from [contributors list](https://github.com/dartclub/turf_dart/graphs/contributors) 
+
+
+## Documentation
+We follow [Effective Dart](https://dart.dev/guides/language/effective-dart/documentation) guidelines for documentation.
+
+After going through the [Implementation Process](#implementation-process), please mention the made changes in [README.md](https://github.com/dartclub/turf_dart/blob/main/README.md)
+
+In order to add to this very documentation, please develop CONTRIBUTING.md in [documentation branch](https://github.com/dartclub/turf_dart/tree/documentation)
+
+## GeoJSON Object Model
+If you have not read our [README.md](https://github.com/dartclub/turf_dart/blob/main/README.md) this diagram will give you a lot of information. Please consider looking our [notable design decisions](https://github.com/dartclub/turf_dart/blob/main/README.md#notable-design-decisions).  
+![polymorphism](https://user-images.githubusercontent.com/10634693/159876354-f9da2f37-02b3-4546-b32a-c0f82c372272.png)
diff --git a/benchmark/cluster_benchmark.dart b/benchmark/cluster_benchmark.dart
@@ -27,10 +27,8 @@ void main() {
 
     benchmark('clusterEach', () {
       List clusters = [];
-      int total = 0;
       clusterEach(featureCollection, "cluster",
           (cluster, clusterValue, currentIndex) {
-        total += cluster!.features.length;
         clusters.add(cluster);
       });
     });

diff --git a/lib/src/bearing.dart b/lib/src/bearing.dart
@@ -3,6 +3,9 @@ import 'dart:math';
 import 'geojson.dart';
 import 'helpers.dart';
 
+// http://en.wikipedia.org/wiki/Haversine_formula
+// http://www.movable-type.co.uk/scripts/latlong.html
+
 num bearingRaw(Position start, Position end, {bool calcFinal = false}) {
   // Reverse calculation
   if (calcFinal == true) {
@@ -19,6 +22,22 @@ num bearingRaw(Position start, Position end, {bool calcFinal = false}) {
   return radiansToDegrees(atan2(a, b));
 }
 
+/// Takes two [Point]s and finds the geographic bearing between them,
+/// i.e. the angle measured in degrees from the north line (0 degrees)
+/// For example:
+///
+/// ```dart
+/// var point1 = Point(coordinates: Position(-75.343, 39.984));
+/// var point2 = Point(coordinates: Position((-75.543, 39.123));
+///
+/// var bearing = bearing(point1, point2);
+/// //addToMap
+/// var addToMap = [point1, point2]
+/// point1.properties['marker-color'] = '#f00'
+/// point2.properties['marker-color'] = '#0f0'
+/// point1.properties.bearing = bearing
+/// ```
+
 num bearing(Point start, Point end, {bool calcFinal = false}) =>
     bearingRaw(start.coordinates, end.coordinates, calcFinal: calcFinal);
 
@@ -28,5 +47,6 @@ num calculateFinalBearingRaw(Position start, Position end) {
   return reverseBearing.remainder(360);
 }
 
+/// Calculates Final Bearing
 num calculateFinalBearing(Point start, Point end) =>
     calculateFinalBearingRaw(start.coordinates, end.coordinates);
diff --git a/lib/src/destination.dart b/lib/src/destination.dart
@@ -22,6 +22,25 @@ Position destinationRaw(Position origin, num distance, num bearing,
   );
 }
 
+/// Takes a [Point] and calculates the location of a destination point given a distance in
+/// degrees, radians, miles, or kilometers; and bearing in degrees.
+/// This uses the [Haversine formula](http://en.wikipedia.org/wiki/Haversine_formula) to account for global curvature.
+/// For example:
+///
+/// ```dart
+/// var point = Point(coordinates: Position(-75.343, 39.984));
+/// var distance = 50;
+/// var bearing = 90;
+/// var options = Unit.miles;
+///
+/// var destination = destination(point, distance, bearing, options);
+///
+/// //addToMap
+/// var addToMap = [point, destination]
+/// destination.properties['marker-color'] = '#f00';
+/// point.properties['marker-color'] = '#0f0';
+/// ```
+
 Point destination(Point origin, num distance, num bearing,
         [Unit unit = Unit.kilometers]) =>
     Point(

diff --git a/lib/src/distance.dart b/lib/src/distance.dart
@@ -3,6 +3,9 @@ import 'dart:math';
 import 'geojson.dart';
 import 'helpers.dart';
 
+//http://en.wikipedia.org/wiki/Haversine_formula
+//http://www.movable-type.co.uk/scripts/latlong.html
+
 num distanceRaw(Position from, Position to, [Unit unit = Unit.kilometers]) {
   var dLat = degreesToRadians((to.lat - from.lat));
   var dLon = degreesToRadians((to.lng - from.lng));
@@ -14,5 +17,16 @@ num distanceRaw(Position from, Position to, [Unit unit = Unit.kilometers]) {
   return radiansToLength(2 * atan2(sqrt(a), sqrt(1 - a)), unit);
 }
 
+/// Calculates the distance between two [Point]s in degrees, radians, miles, or kilometers.
+///  This uses the [Haversine formula](http://en.wikipedia.org/wiki/Haversine_formula) to account for global curvature.
+///  For example:
+///
+/// ```dart
+/// var from = Point(coordinates: Position(-75.343, 39.984));
+/// var to = Point(coordinates: Position(-75.443, 39.984));
+/// var options = Unit.miles;
+///
+/// var distance = distance(from, to, options);
+/// ```
 num distance(Point from, Point to, [Unit unit = Unit.kilometers]) =>
     distanceRaw(from.coordinates, to.coordinates, unit);
diff --git a/lib/src/helpers.dart b/lib/src/helpers.dart
@@ -30,8 +30,11 @@ enum Corner {
   centroid,
 }
 
+/// Earth Radius used with the Harvesine formula and approximates using a spherical (non-ellipsoid) Earth.
 const earthRadius = 6371008.8;
 
+/// Unit of measurement factors using a spherical (non-ellipsoid) earth radius.
+/// Keys are the name of the unit, values are the number of that unit in a single radian
 const factors = <Unit, num>{
   Unit.centimeters: earthRadius * 100,
   Unit.degrees: earthRadius / 111325,
@@ -60,6 +63,7 @@ const unitsFactors = <Unit, num>{
   Unit.yards: 1 / 1.0936,
 };
 
+/// Area of measurement factors based on 1 square meter.
 const areaFactors = <Unit, num>{
   Unit.acres: 0.000247105,
   Unit.centimeters: 10000,
@@ -72,6 +76,7 @@ const areaFactors = <Unit, num>{
   Unit.yards: 1.195990046,
 };
 
+/// Round number to precision
 num round(num value, [num precision = 0]) {
   if (!(precision >= 0)) {
     throw Exception("precision must be a positive number");
@@ -81,6 +86,8 @@ num round(num value, [num precision = 0]) {
   return result.round() / multiplier;
 }
 
+/// Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit.
+/// Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
 num radiansToLength(num radians, [Unit unit = Unit.kilometers]) {
   var factor = factors[unit];
   if (factor == null) {
@@ -89,6 +96,8 @@ num radiansToLength(num radians, [Unit unit = Unit.kilometers]) {
   return radians * factor;
 }
 
+/// Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians
+/// Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
 num lengthToRadians(num distance, [Unit unit = Unit.kilometers]) {
   num? factor = factors[unit];
   if (factor == null) {
@@ -97,10 +106,14 @@ num lengthToRadians(num distance, [Unit unit = Unit.kilometers]) {
   return distance / factor;
 }
 
+/// Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees
+/// Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet
 num lengthToDegrees(num distance, [Unit unit = Unit.kilometers]) {
   return radiansToDegrees(lengthToRadians(distance, unit));
 }
 
+/// Converts any bearing angle from the north line direction (positive clockwise)
+/// and returns an angle between 0-360 degrees (positive clockwise), 0 being the north line
 num bearingToAzimuth(num bearing) {
   num angle = bearing.remainder(360);
   if (angle < 0) {
@@ -109,16 +122,20 @@ num bearingToAzimuth(num bearing) {
   return angle;
 }
 
+/// Converts an angle in radians to degrees
 num radiansToDegrees(num radians) {
   num degrees = radians.remainder(2 * pi);
   return degrees * 180 / pi;
 }
 
+/// Converts an angle in degrees to radians
 num degreesToRadians(num degrees) {
   num radians = degrees.remainder(360);
   return radians * pi / 180;
 }
 
+/// Converts a length to the requested unit.
+/// Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
 num convertLength(
   num length, [
   Unit originalUnit = Unit.kilometers,
@@ -130,6 +147,8 @@ num convertLength(
   return radiansToLength(lengthToRadians(length, originalUnit), finalUnit);
 }
 
+/// Converts a area to the requested unit.
+/// Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, acres, miles, yards, feet, inches, hectares
 num convertArea(num area,
     [originalUnit = Unit.meters, finalUnit = Unit.kilometers]) {
   if (area < 0) {

diff --git a/lib/src/invariant.dart b/lib/src/invariant.dart
@@ -26,11 +26,12 @@ Position getCoord(dynamic coord) {
   throw Exception("coord must be GeoJSON Point or Position");
 }
 
-/// Unwrap coordinates from a [Feature], [GeometryObject] or a [List]
+/// Unwraps coordinates from a [Feature], [GeometryObject] or a [List]
 ///
 /// Gets a [List<dynamic>], [GeometryObject] or a [Feature] or a [List<dynamic>] and
 /// returns [List<dynamic>].
 /// For example:
+///
 /// ```dart
 /// var polygon = Polygon(coordinates: [
 ///    [

diff --git a/lib/src/line_segment.dart b/lib/src/line_segment.dart
@@ -3,8 +3,6 @@ import 'package:turf/src/meta/flatten.dart';
 
 import 'geojson.dart';
 
-// export default lineSegment;
-
 /// Creates a [FeatureCollection] of 2-vertex [LineString] segments from a
 /// [LineString] or [MultiLineString] or [Polygon] and [MultiPolygon]
 /// Returns [FeatureCollection<LineString>] 2-vertex line segments
@@ -210,7 +208,7 @@ typedef T? SegmentReduceCallback<T>(
   int segmentIndex,
 );
 
-/// Reduce 2-vertex line segment in any GeoJSON object, similar to [Iterable.reduce]()
+/// Reduces 2-vertex line segment in any GeoJSON object, similar to [Iterable.reduce]()
 /// (Multi)Point geometries do not contain segments therefore they are ignored during this operation.
 ///
 /// Takes [FeatureCollection], [Feature], [GeoJSONObject], a

diff --git a/lib/src/meta/extensions.dart b/lib/src/meta/extensions.dart
@@ -7,7 +7,7 @@ extension GeoJSONObjectMetaExtension on GeoJSONObject {
   }
 
   T? geomReduce<T>(meta.GeomReduceCallback<T> callback, T? initialValue) {
-    meta.geomReduce<T>(
+    return meta.geomReduce<T>(
       this,
       callback,
       initialValue,
@@ -22,7 +22,7 @@ extension GeoJSONObjectMetaExtension on GeoJSONObject {
     meta.PropReduceCallback<T> callback,
     T? initialValue,
   ) {
-    meta.propReduce<T>(
+    return meta.propReduce<T>(
       this,
       callback,
       initialValue,
@@ -37,7 +37,7 @@ extension GeoJSONObjectMetaExtension on GeoJSONObject {
     meta.FeatureReduceCallback<T> callback,
     T? initialValue,
   ) {
-    meta.featureReduce<T>(
+    return meta.featureReduce<T>(
       this,
       callback,
       initialValue,
@@ -53,7 +53,7 @@ extension GeoJSONObjectMetaExtension on GeoJSONObject {
     T? initialValue, [
     bool excludeWrapCoord = false,
   ]) {
-    meta.coordReduce<T>(
+    return meta.coordReduce<T>(
       this,
       callback,
       initialValue,
@@ -73,7 +73,7 @@ extension GeoJSONObjectMetaExtension on GeoJSONObject {
     meta.FlattenReduceCallback<T> callback,
     T? initialValue,
   ) {
-    meta.flattenReduce<T>(
+    return meta.flattenReduce<T>(
       this,
       callback,
       initialValue,
@@ -89,7 +89,7 @@ extension GeoJSONObjectMetaExtension on GeoJSONObject {
     T? initialValue, {
     bool combineNestedGeometries = true,
   }) {
-    meta.segmentReduce<T>(
+    return meta.segmentReduce<T>(
       this,
       callback,
       initialValue,
@@ -115,7 +115,7 @@ extension FeatureCollectionMetaExtension on FeatureCollection {
     meta.ClusterReduceCallback<T> callback,
     dynamic initialValue,
   ) {
-    meta.clusterReduce<T>(
+    return meta.clusterReduce<T>(
       this,
       property,
       callback,