| Name | fmtm-splitter JSON |
| Version |
1.1.2
JSON |
| download |
| home_page | |
| Summary | A utility for splitting an AOI into multiple tasks. |
| upload_time | 2024-02-15 09:53:19 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.10 |
| license | GPL-3.0-only |
| keywords |
fmtm
odk
hot
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# FMTM Splitter
<!-- markdownlint-disable -->
<p align="center">
<img src="https://github.com/hotosm/fmtm/blob/main/images/hot_logo.png?raw=true" style="width: 200px;" alt="HOT"></a>
</p>
<p align="center">
<em>A utility for splitting an AOI into multiple tasks.</em>
</p>
<p align="center">
<a href="https://github.com/hotosm/fmtm-splitter/actions/workflows/build.yml" target="_blank">
<img src="https://github.com/hotosm/fmtm-splitter/actions/workflows/build.yml/badge.svg" alt="Build">
</a>
<a href="https://github.com/hotosm/fmtm-splitter/actions/workflows/build-ci.yml" target="_blank">
<img src="https://github.com/hotosm/fmtm-splitter/workflows/Build CI Img/badge.svg" alt="CI Build">
</a>
<a href="https://github.com/hotosm/fmtm-splitter/actions/workflows/docs.yml" target="_blank">
<img src="https://github.com/hotosm/fmtm-splitter/workflows/Publish Docs/badge.svg" alt="Publish Docs">
</a>
<a href="https://github.com/hotosm/fmtm-splitter/actions/workflows/publish.yml" target="_blank">
<img src="https://github.com/hotosm/fmtm-splitter/actions/workflows/publish.yml/badge.svg" alt="Publish">
</a>
<a href="https://github.com/hotosm/fmtm-splitter/actions/workflows/pytest.yml" target="_blank">
<img src="https://github.com/hotosm/fmtm-splitter/workflows/PyTest/badge.svg" alt="Test">
</a>
<a href="https://pypi.org/project/fmtm-splitter" target="_blank">
<img src="https://img.shields.io/pypi/v/fmtm-splitter?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypistats.org/packages/fmtm-splitter" target="_blank">
<img src="https://img.shields.io/pypi/dm/fmtm-splitter.svg" alt="Downloads">
</a>
<a href="https://github.com/hotosm/fmtm-splitter/blob/main/LICENSE.md" target="_blank">
<img src="https://img.shields.io/github/license/hotosm/fmtm-splitter.svg" alt="License">
</a>
</p>
---
📖 **Documentation**: <a href="https://hotosm.github.io/fmtm-splitter/" target="_blank">https://hotosm.github.io/fmtm-splitter/</a>
🖥️ **Source Code**: <a href="https://github.com/hotosm/fmtm-splitter" target="_blank">https://github.com/hotosm/fmtm-splitter</a>
---
<!-- markdownlint-enable -->
This is a program to split polygons into tasks using a variety of
algorithms. It is a class that can be used by other projects, but also
a standalone program. It was originally developed for the
[FMTM](https://github.com/hotosm/fmtm/wiki) project, but then
converted so it can be used by multiple projects.
The class takes GeoJson Polygon as an input, and returns a GeoJson
file Multipolygon of all the task boundaries.
## Installation
To install fmtm-splitter, you can use pip. Here are two options:
- Directly from the main branch:
`pip install git+https://github.com/hotosm/fmtm-splitter.git`
- Latest on PyPi:
`pip install fmtm-splitter`
## Splitting Types
### Split By Square
The default is to split the polygon into squares. The default
dimension is 50 meters, but that is configurable. The outer square are
clipped to the AOI boundary.
### Split By Feature
The split by feature uses highway data extracted from OpenStreetMap,
and uses it to generate non square task boundaries. It can also be
adjusted to use the number of buildings in a task to adjust it's
size.
### Custom SQL query
It is also possible to supply a custom SQL query to generate the
tasks.
## Usage In Code
- Either the FMTMSplitter class can be used directly, or the wrapper/
helper functions can be used for splitting.
By square:
```python
import json
from fmtm_splitter.splitter import split_by_square
aoi = json.load("/path/to/file.geojson")
split_features = split_by_square(
aoi,
meters=100,
)
```
The FMTM splitter algorithm:
```python
import json
from fmtm_splitter.splitter import split_by_sql
aoi = json.load("/path/to/file.geojson")
osm_extracts = json.load("/path/to/file.geojson")
db = "postgresql://postgres:postgres@localhost/postgres"
split_features = split_by_sql(
aoi,
db,
num_buildings=50,
osm_extract=osm_extracts,
)
```
### Database Connections
- The db parameter can be a connection string to start a new connection.
- Or an existing database connection can be reused.
- To do this, either the psycopg2 connection, or a SQLAlchemy Session
must be passed:
SQLAlchemy example:
```python
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from fmtm_splitter.splitter import split_by_sql
# Creates a SQLAlchemy Session object
engine = create_engine("postgresql://postgres:postgres@localhost/postgres")
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
db = SessionLocal()
# Then pass this object as the db param
split_features = split_by_sql(
aoi,
db,
num_buildings=50,
osm_extract=osm_extracts,
)
```
psycopg2 example:
```python
import psycopg2
from fmtm_splitter.splitter import split_by_sql
db = psycopg2.connect("postgresql://postgres:postgres@localhost/postgres")
split_features = split_by_sql(
aoi,
db,
num_buildings=50,
osm_extract=osm_extracts,
)
```
## Usage Via CLI
Options:
```bash
-h, --help show this help message and exit
-v, --verbose verbose output
-o OUTFILE, --outfile OUTFILE Output file from splitting
-m METERS, --meters METERS Size in meters if using square splitting
-b BOUNDARY, --boundary BOUNDARY Polygon AOI
-s SOURCE, --source SOURCE Source data, Geojson or PG:[dbname]
-c CUSTOM, --custom CUSTOM Custom SQL query for database
```
This program splits a Polygon (the Area Of Interest)
The data source for existing data can'be either the data extract
used by the XLSForm, or a postgresql database.
Examples:
```bash
fmtm-splitter -b AOI
fmtm-splitter -v -b AOI -s data.geojson
fmtm-splitter -v -b AOI -s PG:colorado
# Where AOI is the boundary of the project as a polygon
# And OUTFILE is a MultiPolygon output file,which defaults to fmtm.geojson
# The task splitting defaults to squares, 50 meters across
```
### Using the Container Image
- fmtm-splitter scripts can be used via the pre-built container images.
- These images come with all dependencies bundled, so are simple to run.
- They do however require a database, to in this case we use docker compose.
Run a specific command:
```bash
docker compose run --rm splitter fmtm-splitter <flags>
```
Run interactively (to use multiple commands):
```bash
docker compose run -it splitter bash
fmtm-splitter
```
> Note: the `output` directory in this repo is mounted in the container
> to `/data/output`. To persist data, input and output should be placed here.
Raw data
{
"_id": null,
"home_page": "",
"name": "fmtm-splitter",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "fmtm,odk,hot",
"author": "",
"author_email": "Rob Savoye <rob.savoye@hotosm.org>,Sam Woodcock <sam.woodcock@hotosm.org>",
"download_url": "https://files.pythonhosted.org/packages/aa/a3/c6f7ae6f9867b823cd87fdb80285b66df30470968592801bd419b8f92898/fmtm-splitter-1.1.2.tar.gz",
"platform": null,
"description": "# FMTM Splitter\n\n<!-- markdownlint-disable -->\n<p align=\"center\">\n <img src=\"https://github.com/hotosm/fmtm/blob/main/images/hot_logo.png?raw=true\" style=\"width: 200px;\" alt=\"HOT\"></a>\n</p>\n<p align=\"center\">\n <em>A utility for splitting an AOI into multiple tasks.</em>\n</p>\n<p align=\"center\">\n <a href=\"https://github.com/hotosm/fmtm-splitter/actions/workflows/build.yml\" target=\"_blank\">\n <img src=\"https://github.com/hotosm/fmtm-splitter/actions/workflows/build.yml/badge.svg\" alt=\"Build\">\n </a>\n <a href=\"https://github.com/hotosm/fmtm-splitter/actions/workflows/build-ci.yml\" target=\"_blank\">\n <img src=\"https://github.com/hotosm/fmtm-splitter/workflows/Build CI Img/badge.svg\" alt=\"CI Build\">\n </a>\n <a href=\"https://github.com/hotosm/fmtm-splitter/actions/workflows/docs.yml\" target=\"_blank\">\n <img src=\"https://github.com/hotosm/fmtm-splitter/workflows/Publish Docs/badge.svg\" alt=\"Publish Docs\">\n </a>\n <a href=\"https://github.com/hotosm/fmtm-splitter/actions/workflows/publish.yml\" target=\"_blank\">\n <img src=\"https://github.com/hotosm/fmtm-splitter/actions/workflows/publish.yml/badge.svg\" alt=\"Publish\">\n </a>\n <a href=\"https://github.com/hotosm/fmtm-splitter/actions/workflows/pytest.yml\" target=\"_blank\">\n <img src=\"https://github.com/hotosm/fmtm-splitter/workflows/PyTest/badge.svg\" alt=\"Test\">\n </a>\n <a href=\"https://pypi.org/project/fmtm-splitter\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/fmtm-splitter?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n </a>\n <a href=\"https://pypistats.org/packages/fmtm-splitter\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/dm/fmtm-splitter.svg\" alt=\"Downloads\">\n </a>\n <a href=\"https://github.com/hotosm/fmtm-splitter/blob/main/LICENSE.md\" target=\"_blank\">\n <img src=\"https://img.shields.io/github/license/hotosm/fmtm-splitter.svg\" alt=\"License\">\n </a>\n</p>\n\n---\n\n\ud83d\udcd6 **Documentation**: <a href=\"https://hotosm.github.io/fmtm-splitter/\" target=\"_blank\">https://hotosm.github.io/fmtm-splitter/</a>\n\n\ud83d\udda5\ufe0f **Source Code**: <a href=\"https://github.com/hotosm/fmtm-splitter\" target=\"_blank\">https://github.com/hotosm/fmtm-splitter</a>\n\n---\n\n<!-- markdownlint-enable -->\n\nThis is a program to split polygons into tasks using a variety of\nalgorithms. It is a class that can be used by other projects, but also\na standalone program. It was originally developed for the\n[FMTM](https://github.com/hotosm/fmtm/wiki) project, but then\nconverted so it can be used by multiple projects.\n\nThe class takes GeoJson Polygon as an input, and returns a GeoJson\nfile Multipolygon of all the task boundaries.\n\n## Installation\n\nTo install fmtm-splitter, you can use pip. Here are two options:\n\n- Directly from the main branch:\n `pip install git+https://github.com/hotosm/fmtm-splitter.git`\n\n- Latest on PyPi:\n `pip install fmtm-splitter`\n\n## Splitting Types\n\n### Split By Square\n\nThe default is to split the polygon into squares. The default\ndimension is 50 meters, but that is configurable. The outer square are\nclipped to the AOI boundary.\n\n### Split By Feature\n\nThe split by feature uses highway data extracted from OpenStreetMap,\nand uses it to generate non square task boundaries. It can also be\nadjusted to use the number of buildings in a task to adjust it's\nsize.\n\n\n\n### Custom SQL query\n\nIt is also possible to supply a custom SQL query to generate the\ntasks.\n\n## Usage In Code\n\n- Either the FMTMSplitter class can be used directly, or the wrapper/\n helper functions can be used for splitting.\n\nBy square:\n\n```python\nimport json\nfrom fmtm_splitter.splitter import split_by_square\n\naoi = json.load(\"/path/to/file.geojson\")\n\nsplit_features = split_by_square(\n aoi,\n meters=100,\n)\n```\n\nThe FMTM splitter algorithm:\n\n```python\nimport json\nfrom fmtm_splitter.splitter import split_by_sql\n\naoi = json.load(\"/path/to/file.geojson\")\nosm_extracts = json.load(\"/path/to/file.geojson\")\ndb = \"postgresql://postgres:postgres@localhost/postgres\"\n\nsplit_features = split_by_sql(\n aoi,\n db,\n num_buildings=50,\n osm_extract=osm_extracts,\n)\n```\n\n### Database Connections\n\n- The db parameter can be a connection string to start a new connection.\n- Or an existing database connection can be reused.\n- To do this, either the psycopg2 connection, or a SQLAlchemy Session\n must be passed:\n\nSQLAlchemy example:\n\n```python\nfrom sqlalchemy import create_engine\nfrom sqlalchemy.orm import sessionmaker\nfrom fmtm_splitter.splitter import split_by_sql\n\n# Creates a SQLAlchemy Session object\nengine = create_engine(\"postgresql://postgres:postgres@localhost/postgres\")\nSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)\ndb = SessionLocal()\n\n# Then pass this object as the db param\nsplit_features = split_by_sql(\n aoi,\n db,\n num_buildings=50,\n osm_extract=osm_extracts,\n)\n```\n\npsycopg2 example:\n\n```python\nimport psycopg2\nfrom fmtm_splitter.splitter import split_by_sql\n\ndb = psycopg2.connect(\"postgresql://postgres:postgres@localhost/postgres\")\n\nsplit_features = split_by_sql(\n aoi,\n db,\n num_buildings=50,\n osm_extract=osm_extracts,\n)\n```\n\n## Usage Via CLI\n\nOptions:\n\n```bash\n-h, --help show this help message and exit\n-v, --verbose verbose output\n-o OUTFILE, --outfile OUTFILE Output file from splitting\n-m METERS, --meters METERS Size in meters if using square splitting\n-b BOUNDARY, --boundary BOUNDARY Polygon AOI\n-s SOURCE, --source SOURCE Source data, Geojson or PG:[dbname]\n-c CUSTOM, --custom CUSTOM Custom SQL query for database\n```\n\nThis program splits a Polygon (the Area Of Interest)\nThe data source for existing data can'be either the data extract\nused by the XLSForm, or a postgresql database.\n\nExamples:\n\n```bash\nfmtm-splitter -b AOI\nfmtm-splitter -v -b AOI -s data.geojson\nfmtm-splitter -v -b AOI -s PG:colorado\n\n# Where AOI is the boundary of the project as a polygon\n# And OUTFILE is a MultiPolygon output file,which defaults to fmtm.geojson\n# The task splitting defaults to squares, 50 meters across\n```\n\n### Using the Container Image\n\n- fmtm-splitter scripts can be used via the pre-built container images.\n- These images come with all dependencies bundled, so are simple to run.\n- They do however require a database, to in this case we use docker compose.\n\nRun a specific command:\n\n```bash\ndocker compose run --rm splitter fmtm-splitter <flags>\n```\n\nRun interactively (to use multiple commands):\n\n```bash\ndocker compose run -it splitter bash\n\nfmtm-splitter\n```\n\n> Note: the `output` directory in this repo is mounted in the container\n> to `/data/output`. To persist data, input and output should be placed here.\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "A utility for splitting an AOI into multiple tasks.",
"version": "1.1.2",
"project_urls": {
"documentation": "https://hotosm.github.io/fmtm-splitter",
"homepage": "https://hotosm.github.io/fmtm-splitter",
"repository": "https://github.com/hotosm/fmtm-splitter"
},
"split_keywords": [
"fmtm",
"odk",
"hot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9d714c57a67a448de9f58df7ee7483b09c1905d8b3292d0699c836f3c64de1d2",
"md5": "ee3dc0300615cc2aa68c0ec07512ccc0",
"sha256": "9ffe3381c1ef435f0a5fa9595515ba4748d822317434c34830740908249048a7"
},
"downloads": -1,
"filename": "fmtm_splitter-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee3dc0300615cc2aa68c0ec07512ccc0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 50067,
"upload_time": "2024-02-15T09:53:17",
"upload_time_iso_8601": "2024-02-15T09:53:17.723008Z",
"url": "https://files.pythonhosted.org/packages/9d/71/4c57a67a448de9f58df7ee7483b09c1905d8b3292d0699c836f3c64de1d2/fmtm_splitter-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aaa3c6f7ae6f9867b823cd87fdb80285b66df30470968592801bd419b8f92898",
"md5": "3ff0494086aee70835bf171652ca362b",
"sha256": "e6881e04ee2491f7ce3cb50827a2d05d8274228cb0390ddf2e5fbd62f7195c8e"
},
"downloads": -1,
"filename": "fmtm-splitter-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "3ff0494086aee70835bf171652ca362b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 39264,
"upload_time": "2024-02-15T09:53:19",
"upload_time_iso_8601": "2024-02-15T09:53:19.351448Z",
"url": "https://files.pythonhosted.org/packages/aa/a3/c6f7ae6f9867b823cd87fdb80285b66df30470968592801bd419b8f92898/fmtm-splitter-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-15 09:53:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hotosm",
"github_project": "fmtm-splitter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fmtm-splitter"
}
