poly 1.0.6

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • new73

poly #

Pub build status

A library for checking if given point(s) is present inside Polygon or not.

Contents #

Installation #

To install poly for your Dart project, simply add poly to your pub dependencies.

dependencies:
    poly^ 1.0.5

Examples #

1. A very simple usage example #

  1. Creates 2 Polygons from List<Point>
  2. Checks if 2 Polygon have same vertices i.e. points : using hasSamePoint()
  3. Prints if given Points are inside Polygon
  4. Prints if all points in list are inside Polygon or not
  5. Prints list of result for List of points if they are inside Polygon or not
  • Here hasSamePoint(), isPointInside(Point( )), contains(x,y), areAllPointsInsidePolygon_ListPoint() & getList_IsListOfPointInside() are used.

2. Example of Conversions List <=> Point, List<Point> <=> List<List> & other #

  1. Example of toPoint()
    • toPoint() converts List<num> to Point<num>
  2. Example of toListOfPoint()
    • toListOfPoint() converts List<List<num>> to List<Point<num>>
  3. Example of toPolyFromListOfList()
    • toPolyFromListOfList() converts List<List<num>> to Polygon
    • Print status of List of List if they are inside our Polygon using getList_IsListOfListInside
    • Print if All points in List of List inside Polygon using

3. Examples of List<dynamic> => List<num> and List<List<dynamic>> => List<List<num>> #

  • toListNum() returns List<num> from a List<dynamic>
  • toListListNum() returns List<List<num>> from a List<List<dynamic>>
  1. Examples of toListNum()
    • without any optional parameters
    • with replaceWithZero: true and sizeTwo: false
    • with sizeTwo: false
  2. Examples of toListListNum()
    • without any optional parameters
    • with swapXAndY: true
    • with replaceWithZero: true
    • with replaceWithZero: true and swapXAndY: true

4. Simple CSV example #

  • It contains examples of following functions -
  1. Example of IsInsideResultWithXY_ToCSVString

    • Saving ArePointsInside Results to "IsInside.csv"
      • Headers row will be added, as includeHeader isnt passed asfalse`
      • And as diffNameThanIsInside:"Example String" is passed,
      • Header row will be latitude,longitude,Example String
  2. Example of toCSVString

    • Saving Polygon.points to "Polygon.csv"
      • Headers row will be added, as includeHeader isnt passed asfalse`
      • And as useXY is passed as true
      • Header row will be x,y
  3. Example of csvToResult

    • Display 1st row : 2nd element & 3rd element of "IsInside.csv"
      • e.g. here "longitude" and "Example String"
      • As, previously xY_IsInside_ToCSVString returned String with header
      • because optional parameter header was not set to false
  4. Example of csvToPoly

    • Check if Point(18.507305, 73.806131) is inside Polygon readPolygon (Polygon from Polygon.csv)

5. Exception Handling Example #

  • It contains examples of following exceptions & errors -
  1. NeedsAtLeastThreePoints is thrown if Polygon.points contains less than 3 points
  2. WrongSizeForPoint is thrown if toPoint() has more or less than 2 element. Point has only x and y.
  3. TypeError is thrown if List<dynamic> is passed instead of List<num>
    • Here, casting can be used to cast List<dynamic> to List<num>
    • e.g. print(toPoint([1,2]));
      • Here, [1,2] has a type List<dynamic>
      • So, use [1,2].cast<num>()
  4. CastError example - wrongly casting List<num> to List<List<num>

6. Easy Casting Example #

  • Without casting List<dynamic> to List<num> TypeErroris thrown
  1. Correct casting

    • casting List<dynamic> to List<num>
    • casting List<dynamic> to List<List<num>>
  2. Passing List instead of List<List>

  • Passing List instead of List<List> & casting it : throws CastError as shown below :

    type int is not a subtype of type List<num> in type cast

  • Passing List instead of List<List> but, without casting it : throws TypeError as shown below :

    type List<dynamic> is not a subtype of type List<List<num>>

  • Note: currently casting List<List<dynamic>> to List<List<num>> gives following CastError exception:
    • without as List<List<num>> -

    type List<dynamic> is not a subtype of type List<num> in type cast

    • with as List<List<num>> -

    type List<List<dynamic>> is not a subtype of type List<List<num>> in type cast

Note: Instead of casting, use toListNum() & toListListNum()

  • Use toListNum() for List<dynamic> => List<num>
  • Use toListListNum() forList<List<dynamic>> => List<List<num>>

Function List #

Conversion Type #

List<num> to Point(x,y) : use toPoint()
  • i.e. [x,y] -> Point(x,y)
  • Point can be created passing List<num> toPoint().
  • List must have exact 2 elements, else will throw WrongSizeForPoint exception
List<List<num>> to List<Point<num>> : use toListOfPoint()
  • i.e. [ [x1,y1],[x2,y2],... ] -> [ Point(x1,y1), Point(x2,y2),... ]
  • List of Points can be created from List<List<num>> by passing it to toListOfPoint()
List<List<num>> to Polygon : use toPolyFromListOfList()
  • i.e. [ [x1,y1],[x2,y2],... ] -> Polygon( Point(x1,y1), Point(x2,y2),... )
  • Polygon can be returned from List<List<num>> by passing it to toPolyFromListOfList
List<dynamic> to List<num> : use toListNum()
  • Returns List<num> from a List<dynamic>
  • Can be used with [toPoly] as it accepts List<num>
  • Optional Parameters -
    • sizeTwo
      • Default value true
      • When set false, Output List can have more than 2 elements
    • replaceWithZero
      • Default value false
      • When set true, elements with type String or bool will be replaced with 0, rather than being removed
    • reverseIt
      • Default value false
      • When set true, List will be reversed
List<List<dynamic>> to List<List<num>> : use toListListNum()
  • Returns List<List<num>> from a List<List<dynamic>>
  • Can be used with functions like [areAllPointsInsidePolygon_List] , [getList_IsListOfListInside] , [toPolyFromListOfList] , [toListOfPoint] which accepts List<List<num>>
  • Optional Parameters -
    • replaceWithZero
      • Default value false
      • When set true, elements with type String or bool will be replaced with 0, rather than being removed
    • swapXAndY
      • Default value false
      • When set true, xi will be swapped with yi
        • i.e. [ [x1,y1], [x2,y2], ...] -> [ [y1,x1], [y2,x2], ...]

is Point(s) inside #

Check if Single Point is inside
Get Status by passing x and y to contains
  • returns true if (x,y) is present inside Polygon
Get Status by passing Point(x,y) to isPointInside
  • returns true if Point is present inside Polygon
Check if Multiple Points are inside given Polygon #
Get Status of each Point #
  • getList_IsListOfListInside(List<List<num>>) returns List<bool>
  • getList_IsListOfPointInside(List<Point<num>>) returns List<bool>
Check if all given Points are inside given Polygon #
  • areAllPointsInsidePolygon_List((List<List<num>>) returns true or false
  • areAllPointsInsidePolygon_ListPoint(List<Point<num>>) returns true or false

Checks if 2 Polygon have same vertices i.e. points

  • use hasSamePoints()

CSV #

Get result(s) along with lat, lang as a CSV String : IsInsideResultWithXY_ToCSVString() #

  • Returns result of ArePointsInside as CSV String which can be later saved or displayed
  • Output CSV String will by default contain a header row - latitude,longitude,isInside
  • Optional parameter: bool useXY
    • By passing, optional parameter: useXY as true, header will be x,y instead of latitude,longitude
    • Default value of useXY is false
  • Optional parameter: String includeHeader
    • if optional parameter - includeHeader is passed as false, returning String will not contain header row
  • Optional Named parameter: String diffNameThanIsInside
    • Different name than Default name(isInside) will be used by passing optional parameter: diffNameThanIsInside

GetPolygonas CSV String : toCSVString()

  • Returns Polygon as CSV String which can be later saved or displayed
  • Output CSV String will by default contain a header row - latitude,longitude
  • Optional Named parameter: bool useXY
    • By passing, optional parameter: useXY as true, header will be x,y instead of latitude,longitude
    • Default value of useXY is false
  • Optional Named parameter: String includeHeader
    • if optional parameter - includeHeader is is passed as false, returning String will not contain header row

GetFuture<Polygon>based oncsvString: csvToPoly()

  • Returns Future<Polygon> based on csvString
  • csvString may or may not contain header row
  • This function checks if latitude,longitude or x,y are reversed
    • By checking Header row label
    • i.e. By checking 1st row 1st element is neither "longitude" or "y"
    • If they are reversed, Returned Polygon will be Polygon(latitude,longitude), instead of Polygon(longitude,latitude)
    • This can be manually set by passing optional parameter: isReversed as true
  • Optional parameter: isReversed
    • isReversed has default value = false

csvToListOfList() #

  • Returns Future<List<List>> based on csvString
    • which then can be used - convert that list into Polygon
  • Optional parameter: bool noHeader
    • By passing optional parameter: noHeader as true, Resulting List will not contain header row
    • Default value false

Exceptions #

  1. NeedsAtLeastThreePoints is thrown if Polygon.points contains less than 3 points
  2. WrongSizeForPoint is thrown if toPoint() has more or less than 2 element. Point has only x and y.
  3. _TypeError is thrown if List<dynamic> is passed instead of List<num>
    • Here, casting can be used to cast List<dynamic> to List<num>
    • e.g. print(toPoint([1,2]));
      • Here, [1,2] has a type List<dynamic>
      • So, use [1,2].cast<num>()
  4. _CastError example - casting List<num> to List<List<num>

Index #

Features and bugs #

Please file feature requests and bugs at the issue tracker.

Licence #

Implemented contains function logic from StageXL - A fast and universal 2D rendering engine for HTML5 and Dart

As, StageXL imports dart:html, it can not be used in console application or in aqueduct back-end.

Created from templates made available by Stagehand under a BSD-style license.

1.0.0 #

  • Initial version, created by Stagehand
  • Had Polygon, contains()

1.0.1 #

As suggested by pub.dartlang.org analysis

  • Ran dartfmt on poly.dart &
  • Added description in pubspec.yaml

1.0.2 #

As suggested by pub.dartlang.org analysis

  • Removed some description from pubspec.yaml

1.0.3 #

Added following functions & examples for -

1.0.4 #

1.0.5 #

1.0.6 #

  • Updated documentation
  • Added Travis CI - build status

example/poly_example.dart

import 'package:poly/poly.dart';

main() {
  int example_count = 0;
  List<Point<num>> l = [
    Point(18.4851825, 73.8498851),
    Point(18.4849214, 73.8498675),
    Point(18.4855965, 73.8520493),
    Point(18.4859711, 73.8512369),
    Point(18.4857828, 73.8500299),
    Point(18.4851825, 73.8498851)
  ];

  /// List of Points can be passed as parameter to constructor Polygon()
  Polygon testPolygon = Polygon(l);
  // Or Just Pass List inside constructor
  Polygon copyOfFirstPolygon = Polygon([
    Point(18.4851825, 73.8498851),
    Point(18.4849214, 73.8498675),
    Point(18.4855965, 73.8520493),
    Point(18.4859711, 73.8512369),
    Point(18.4857828, 73.8500299),
    Point(18.4851825, 73.8498851)
  ]);
  Point in1 = Point(18.48569, 73.85067);

  /// Example of `hasSamePoint()`
  /// *Checks if 2 `Polygon` have same vertices i.e. `points`
  // * Should print `true`
  print(
      "${++example_count}. `testPolygon` and `copyOfFirstPolygon` are same : ${testPolygon.hasSamePoints(copyOfFirstPolygon)}");

  /// A Point can be checked if it's present inside the Polygon by passing [Point i] to isPointInside function
  // Should Print true
  print(
      "${++example_count}. in1=(18.48569, 73.85067) is inside testWyse - ${testPolygon.isPointInside(in1)}");

  /// X,Y can be checked if they are present inside polygon by passing [x,y] to contains function
  // Should Print true
  print(
      "${++example_count}. Polygon a contains :(18.48569, 73.85067) - ${copyOfFirstPolygon.contains(18.48569, 73.85067)}");

  /// Multiple Points inside a List can be tested by passing it to areAllPointsInsidePolygon_ListPoint
  // Should Print true
  print(
      "${++example_count}. All points in l are within testWyse - ${testPolygon.areAllPointsInsidePolygon_ListPoint(l)}");

  ///areAllPointsInsidePolygon_ListPoint returns true if all Point<num> are inside Polygon
  // Should Print false
  List<Point<num>> notInsidePoints = []..addAll(l)..addAll([Point(75, 90)]);
  print(
      "${++example_count}. All points in notInsidePoints are within testWyse - ${testPolygon.areAllPointsInsidePolygon_ListPoint(notInsidePoints)}");
  //  print("${notInsidePoints}, ${notInsidePoints.runtimeType}");

  /// getList_IsListOfPointInside returns List<bool> as List<Point> if List<Point> are inside Polygon
  // Should Print: [true, true, true, true, true, true, false]
  print(
      "${++example_count}. Status of notInsidePoints - ${testPolygon.getList_IsListOfPointInside(notInsidePoints)}");
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  poly: ^1.0.6

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:poly/poly.dart';
  
Version Uploaded Documentation Archive
1.0.6 Apr 19, 2019 Go to the documentation of poly 1.0.6 Download poly 1.0.6 archive
1.0.5 Apr 18, 2019 Go to the documentation of poly 1.0.5 Download poly 1.0.5 archive
1.0.4 Apr 13, 2019 Go to the documentation of poly 1.0.4 Download poly 1.0.4 archive
1.0.3 Apr 13, 2019 Go to the documentation of poly 1.0.3 Download poly 1.0.3 archive
1.0.2 Apr 2, 2019 Go to the documentation of poly 1.0.2 Download poly 1.0.2 archive
1.0.1 Apr 2, 2019 Go to the documentation of poly 1.0.1 Download poly 1.0.1 archive
1.0.0 Apr 2, 2019 Go to the documentation of poly 1.0.0 Download poly 1.0.0 archive
Popularity:
Describes how popular the package is relative to other packages. [more]
46
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
73
Learn more about scoring.

We analyzed this package on Apr 19, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.2.0
  • pana: 0.12.14

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:poly/poly.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
collection ^1.14.11 1.14.11
csv ^4.0.3 4.0.3
Dev dependencies
pedantic ^1.0.0
test ^1.0.0