https://github.com/sacchid/poly
A dart library to check if given point(s) are present inside polygon or not.
https://github.com/sacchid/poly
dart dart-library flutter-library library polygon
Last synced: 8 months ago
JSON representation
A dart library to check if given point(s) are present inside polygon or not.
- Host: GitHub
- URL: https://github.com/sacchid/poly
- Owner: Sacchid
- License: other
- Created: 2019-04-02T12:12:03.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-04-09T07:20:17.000Z (about 3 years ago)
- Last Synced: 2025-10-23T06:51:42.359Z (8 months ago)
- Topics: dart, dart-library, flutter-library, library, polygon
- Language: Dart
- Size: 275 KB
- Stars: 9
- Watchers: 1
- Forks: 19
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# poly
[](https://pub.dartlang.org/packages/poly)
[](https://travis-ci.org/Sacchid/poly#)
[](https://opensource.org/licenses/BSD-2-Clause)
A library for checking if given point(s) is present inside Polygon or not.
### Contents
* [Installation](#installation)
* [Examples](#examples)
* [Note: Instead of casting, use `toListNum()` & `toListListNum()`](#note-instead-of-casting-use-tolistnum--tolistlistnum)
* [Function List](#function-list)
- [Conversions ](#conversion-type)
- [is Point(s) inside](#is-points-inside)
1. [Check if Single `Point` is inside](#check-if-single-point-is-inside)
2. [Check if Multiple Points are inside given Polygon](#check-if-multiple-points-are-inside-given-polygon)
- [Checks if 2 `Polygon` have same vertices i.e. `points`](#checks-if-2-polygon-have-same-vertices-ie-points)
- [CSV](#csv)
* [Exceptions](#exceptions)
* [Detailed Index](#index)
# Installation
[To install poly for your Dart project, simply add poly to your
pub dependencies.](https://pub.dartlang.org/packages/poly#-installing-tab- "installing poly from pub.dartlang")
dependencies:
poly^ 1.0.5
## Examples
### [1. A very simple usage example ](example/poly_example.dart "Basic example")
1. Creates 2 Polygons from `List`
2. Checks if 2 `Polygon` have same vertices i.e. `points` : using `hasSamePoint()`
2. Prints if given Points are inside Polygon
3. Prints if all points in list are inside Polygon or not
4. 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 <=> List` & other](example/conversion.dart)
1. Example of `toPoint()` & `pointToList()`
* `toPoint()` converts `List` to `Point`
* `pointToList()` converts `Point` to `List`
2. Example of `toListOfPoint()` & `pointsToList()`
* `toListOfPoint()` converts `List>` to `List>`
* `pointsToList()` converts `List>` to `List>`
3. Example of `toPolyFromListOfList()` & `listOfList()`
* `toPolyFromListOfList()` converts `List>` to `Polygon`
* `listOfList()` returns `Polygon.points` as `List>`
* `toPolyFromListOfList()` gives Polygon & `backToListC2()` gives back List>
* 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` => `List` and `List>` => `List>`](example/using_to.dart)
* `toListNum()` returns `List` from a `List`
* `toListListNum()` returns `List>` from a `List>`
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 ](example/simple_csv.dart)
* It contains examples of following functions -
1. Example of `IsInsideResultWithXY_ToCSVString`
* Saving `ArePointsInside Results` to "IsInside.csv"
* Headers row will be added, as `includeHeader` isn`t passed as `false`
* 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` isn`t passed as `false`
* 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](example/exception_handling.dart)
* 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` is passed instead of `List`**
* Here, casting can be used to cast `List` to `List`
* e.g. ` print(toPoint([1,2]));`
* Here, [1,2] has a type `List`
* So, use `[1,2].cast()`
4. `CastError example` - wrongly casting `List` to `List`
### [6. Easy Casting Example](example/easy_casting.dart)
* Without casting `List` to `List` `TypeError`is thrown
1. Correct casting
* casting `List` to `List`
* casting `List` to `List>`
2. Passing `List` instead of `List`
* Passing `List` instead of `List` & casting it : throws `CastError` as shown below :
> type `int` is not a subtype of type `List` in type cast
* Passing `List` instead of `List` but, without casting it : throws `TypeError` as shown below :
> type `List` is not a subtype of type `List>`
* [****Note: currently casting `List>` to `List>` gives following `CastError` exception:****](https://github.com/dart-lang/sdk/issues/36614 "Dart-lang List> to List> Casting Issue")
* without `as List>` -
> type `List` is not a subtype of type `List` in type cast
* with `as List>` -
> type `List>` is not a subtype of type `List>` in type cast
## Note: Instead of casting, use `toListNum()` & `toListListNum()`
* Use `toListNum()` for `List` => `List`
* Use `toListListNum()` for`List>` => `List>`
# Function List
### Conversion Type
##### `List` to `Point(x,y)` : use `toPoint()`
* i.e. `[x,y]` -> `Point(x,y)`
* Point can be created passing `List` `toPoint()`.
* List must have exact 2 elements, else will throw `WrongSizeForPoint` exception
##### `Point(x,y)` to `List` : use `pointToList()`
* i.e. `Point(x,y)` -> `[x,y]`
* List can be created passing `Point(x,y)` `pointToList()`.
##### `List>` to `List>` : use `toListOfPoint()`
* i.e. `[ [x1,y1],[x2,y2],... ]` -> `[ Point(x1,y1), Point(x2,y2),... ]`
* List of Points can be created from `List>` by passing it to `toListOfPoint()`
##### `List>` to `List>` : use `pointsToList()`
* i.e. `[ Point(x1,y1), Point(x2,y2),... ]` -> `[ [x1,y1],[x2,y2],... ]`
* List can be created passing `List>` `pointsToList()`.
##### `List>` to `Polygon` : use `toPolyFromListOfList()`
* i.e. `[ [x1,y1],[x2,y2],... ]` -> `Polygon( Point(x1,y1), Point(x2,y2),... )`
* Polygon can be returned from `List>` by passing it to `toPolyFromListOfList()`
##### `List>` to `Polygon` : use `listOfList()`
* i.e. `[ [x1,y1],[x2,y2],... ]` from `Polygon( Point(x1,y1), Point(x2,y2),... )`
* `List>` can be returned from `Polygon` by passing it to `listOfList()`
##### `List` to `List` : use `toListNum()`
* Returns `List` from a `List`
* Can be used with [toPoly] as it accepts `List`
* 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>` to `List>` : use `toListListNum()`
* Returns `List>` from a `List>`
* Can be used with functions like [areAllPointsInsidePolygon_List] , [getList_IsListOfListInside] , [toPolyFromListOfList] , [toListOfPoint] which accepts `List>`
* 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 Single `Point` is inside Polygon with tolerance of T meter
###### Get Status by passing `Point(x,y)` and Tolerance `T` to `isPointInside`
##### Check if Multiple Points are inside given Polygon
###### Get Status of each Point
* `getList_IsListOfListInside(List>)` returns `List`
* `getList_IsListOfPointInside(List>)` returns `List`
###### Check if all given Points are inside given Polygon
* `areAllPointsInsidePolygon_List((List>)` returns `true` or `false`
* `areAllPointsInsidePolygon_ListPoint(List>)` 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`
#### `Get `Polygon` as 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
#### `Get `Future` based on `csvString` : csvToPoly()`
* Returns `Future` 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>` 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` is passed instead of `List`**
* Here, casting can be used to cast `List` to `List`
* e.g. ` print(toPoint([1,2]));`
* Here, [1,2] has a type `List`
* So, use `[1,2].cast()`
4. `_CastError example` - casting `List` to `List`
### Index
* [Installation](#installation)
* [Examples](#examples)
- [1. A very simple usage example ](#1-a--very-simple-usage-example-examplepoly_exampledart-basic-example)
- [2. Example of Conversions : `List <=> Point`, `List <=> List` & other](#2-example-of-conversions-list--point-listpoint--listlist--otherexampleconversiondart)
- [3. Examples of `List` => `List` and `List>` => `List>`](#3-examples-of-listdynamic--listnum-and-listlistdynamic--listlistnumexampleusing_todart)
- [4. Simple CSV example](#4-simple-csv-example-examplesimple_csvdart)
- [5. Exception Handling Example](#5-exception-handling-exampleexampleexception_handlingdart)
- [6. Easy Casting Example](#6-easy-casting-exampleexampleeasy_castingdart)
* [Note: Instead of casting, use `toListNum()` & `toListListNum()`](#note-instead-of-casting-use-tolistnum--tolistlistnum)
* [Function List](#function-list)
- [Conversions ](#conversion-type)
1. [`toPoint()`](#listnum-to-pointxy--use-topoint)
2. [`toListOfPoint()`](#listlistnum-to-listpointnum--use-tolistofpoint)
3. [`toPolyFromListOfList()`](#listlistnum-to-polygon--use-topolyfromlistoflist)
4. [`toListNum()`](#listdynamic-to-listnum--use-tolistnum)
5. [`toListListNum()`](#listlistdynamic-to-listlistnum--use-tolistlistnum)
- [is Point(s) inside](#is-points-inside)
1. [Check if Single `Point` is inside](#check-if-single-point-is-inside)
* [Get Status by passing `x` and `y` to `contains`](#get-status-by-passing-x-and-y-to-contains)
* [Get Status by passing `Point(x,y)` to `isPointInside`](#get-status-by-passing-pointxy-to-ispointinside)
2. [Check if Multiple Points are inside given Polygon](#check-if-multiple-points-are-inside-given-polygon)
* [Get Status of each Point](#get-status-of-each-point)
* [Check if all given Points are inside given Polygon](#check-if-all-given-points-are-inside-given-polygon)
- [Checks if 2 `Polygon` have same vertices i.e. `points`](#checks-if-2-polygon-have-same-vertices-ie-points)
- [CSV](#csv)
* [`Get result(s) along with lat, lang as a CSV String : IsInsideResultWithXY_ToCSVString()`](#get-results-along-with-lat-lang-as-a-csv-string--isinsideresultwithxy_tocsvstring)
* [`Get `Polygon` as CSV String : toCSVString()`](#get-polygon-as-csv-string--tocsvstring)
* [`Get `Future` based on `csvString` : csvToPoly()`](#get-futurepolygon-based-on-csvstring--csvtopoly)
* [`csvToListOfList()`](#csvtolistoflist)
* [Exceptions](#exceptions)
* [Index](#index)
## Features and bugs
Please file feature requests and bugs at the [issue tracker][tracker].
[tracker]: https://github.com/Sacchid/poly/issues
## Licence
Implemented `contains` function logic from [StageXL - A fast and universal 2D rendering engine for HTML5 and Dart](https://github.com/bp74/StageXL)
As, StageXL imports ``dart:html``, it can not be used in [console application](https://www.dartlang.org/tutorials/server/cmdline) or in [aqueduct back-end](https://aqueduct.io/).
Also, function `distanceInMeter` is implemented by using formulas for [Algorithm](https://edwilliams.org/avform.htm#Dist) & [it's NOAA online calculator](www.nhc.noaa.gov)
Created from templates made available by Stagehand under a BSD-style
[license](https://github.com/dart-lang/stagehand/blob/master/LICENSE).