FMTM Splitter

A utility for splitting an AOI into multiple tasks.

📖 Documentation: https://hotosm.github.io/fmtm-splitter/

🖥️ Source Code: https://github.com/hotosm/fmtm-splitter

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 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:

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:

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:

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:

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:

-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:

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:

docker compose run --rm splitter fmtm-splitter <flags>

Run interactively (to use multiple commands):

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.