OSMToolset.jl
Documentation for OSMToolset.jl
For details please go to the Reference section.
There is also a Visualization example.
Aknowledgments
This research was funded by National Science Centre, Poland grant number 2021/41/B/HS4/03349.
diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 481152f..f22a469 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-31T16:04:20","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-31T16:29:45","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index 08b3c8c..6aa5d3c 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -
Documentation for OSMToolset.jl
For details please go to the Reference section.
There is also a Visualization example.
This research was funded by National Science Centre, Poland grant number 2021/41/B/HS4/03349.
Settings
This document was generated with Documenter.jl version 1.1.2 on Tuesday 31 October 2023. Using Julia version 1.9.3.
Documentation for OSMToolset.jl
For details please go to the Reference section.
There is also a Visualization example.
This research was funded by National Science Centre, Poland grant number 2021/41/B/HS4/03349.
Settings
This document was generated with Documenter.jl version 1.1.2 on Tuesday 31 October 2023. Using Julia version 1.9.3.
OSMToolset.find_poi
— Functionfind_poi(filename::AbstractString; scrape_config::ScrapePOIConfig{T <: MetaPOI}=__builtin_poiconfig)
Generates a DataFrame
with points of interests and from a given XML filename
. The data frame will also contain the metadata from T
for each POI.
The DataFrame
can be later used with AttractivenessSpatIndex
to build an attractivenss spatial index.
The attractiveness values for the index will be used ones from the scrape_config
file. By default __builtin_poiconfig
from __builtin_config_path
will be used but you can define your own index.
OSMToolset.ScrapePOIConfig
— TypeRepresents the configuration of the data scraping process from OSM XML.
Only those pieces of data will be scraped that are defined here.
The configuration is defined in a DataFrame with the following columns: group
, key
, values
, influence
, range
. Instead of the DataFrame a paths to a CSV file can be provided.
ScrapePOIConfig()
- default inbuilt configuration for data scraping. Note that the default configuration can change with library updates. This will use AttractivenessMetaPOI
as meta data.ScrapePOIConfig{T <: MetaPOI}(filename::AbstractString)
- use a CSV file with configurationScrapePOIConfig{T <: MetaPOI}(df::DataFrame)
- use a DataFrame
When the T
parameter is not provided AttractivenessMetaPOI
will be used. When you do not want to use metadata provide NoneMetaPOI
as T
OSMToolset.MetaPOI
— Typeabstract type MetaPOI end
A base time for representing metadata related to a POI location.
OSMToolset.NoneMetaPOI
— Typestruct NoneMetaPOI <: MetaPOI; end
A subtype of MetaPOI
that does not contain any metadata.
OSMToolset.AttractivenessMetaPOI
— Typestruct AttractivenessMetaPOI <: MetaPOI
A subtype of MetaPOI
that contains metadata for attractiveness (the default configuration of scraping). This assumes that the metadata is stored in a CSV file with the following columns: key
, values
, group
, influence
, range
.
OSMToolset.AttractivenessSpatIndex
— TypeAttractivenessSpatIndex{T <: MetaPOI}(filename::AbstractString, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)
-AttractivenessSpatIndex{T <: MetaPOI}(df::AbstractDataFrame, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)
Builds an attractivness spatial index basing on data in some CSV file or a DataFrame
Assuming that T
is of typw AttractivenessMetaPOI
, the CSV file or DataFrame should have the following columns: - group - data group in attractiveness index, each group name creates attractiveness dimension - key - key in the XML file <tag> - values - values in the <tag> (a star "*"
catches all values) - influence - strength of influence - range - maximum influence range in meters
When a DataFrame
is provided the additional parameter refLLA
can be provided for the reference LLA
coordinates in the spatial index. The spatial index works in the ENU coordinate system.
If T
is not provided AttractivenessMetaPOI
will be used as the default metadata type.
The type F
represents the attractiveness group function provided as get_group = (a::T) -> :somegroup
.
OSMToolset.attractiveness
— Functionattractiveness(sindex::AttractivenessSpatIndex{T}, lattitude::Number, longitude::Number; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI
Returns the multidimensional attractiveness measure for the given spatial index sindex
and lattitude
and longitude
. The aggregator
function will be used to aggregate the attractiveness values. The aggreagation is required as more than one point of interest can be found within the attractiveness range. The function calculate_attractiveness(a::T, poidistance::Number)
will be used to calculate the attractiveness on the base of metadata and distance. The distance function distance(a::ENU, b::ENU)
is used to calculate the distance between point pairs.
If explain
is set to true the result will additionally contain details about POIs used to calculate the attractiveness.
attractiveness(sindex::AttractivenessSpatIndex{T}, lla::LLA; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI
Returns the multidimensional attractiveness measure for the given spatial index sindex
and LLA
coordinates. The aggregator
function will be used to aggregate the attractiveness values. The aggreagation is required as more than one point of interest can be found within the attractiveness range. The function calculate_attractiveness(a::T, poidistance::Number)
will be used to calculate the attractiveness on the base of metadata and distance. The distance function distance(a::ENU, b::ENU)
is used to calculate the distance between point pairs.
If explain
is set to true the result will additionally contain details about POIs used to calculate the attractiveness.
attractiveness(sindex::AttractivenessSpatIndex{T}, enu::ENU; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI
Returns the multidimensional attractiveness measure for the given spatial index sindex
and enu
cooridanates. Note that the enu coordinates must use sindex.refLLA
as the reference point. Hence the enu
coordinates need to be calculated eg. using ENU(lla,sindex.refLLA)
. The aggregator
function will be used to aggregate the attractiveness values. The aggreagation is required as more than one point of interest can be found within the attractiveness range. The function calculate_attractiveness(a::T, poidistance::Number)
will be used to calculate the attractiveness on the base of metadata and distance. The distance function distance(a::ENU, b::ENU)
is used to calculate the distance between point pairs.
If explain
is set to true the result will additionally contain details about POIs used to calculate the attractiveness.
OSMToolset.calculate_attractiveness
— Functioncalculate_attractiveness(a::AttractivenessMetaPOI, poidistance::Number)
Default function used to calculate the attractiveness for AttractivenessMetaPOI
on the base of distance. You might want to provide your own implementation and than pass it as a parameter whe using the attractiveness
function.
OSMToolset.get_attractiveness_group
— Functionget_attractiveness_group(a::AttractivenessMetaPOI)
Default group for AttractivenessMetaPOI which is a.group
.
get_attractiveness_group(a::NoneMetaPOI)
Default group for NoneMetaPOI (NoneMetaPOI
).
OSMToolset.clean_pois_by_group
— Functionclean_pois_by_group(df::DataFrame)
For data imported via AttractivenessMetaPOI the function will return only the most attractive POI for each group. This is useful when you want to remove duplicate entries for the same node.
OSMToolset.NodeSpatIndex
— TypeNodeSpatIndex(md::MapData, refLLA::LLA = OpenStreetMapX.center(md.bounds); node_range::Number=100.0)
Create a spatial index for nodes in the md
using refLLA
as the reference for ENU coordinates with the given node_range
in meters.
NodeSpatIndex(nodes::AbstractVector{Int64}, lattitudes::AbstractVector{Float64}, longitudes::AbstractVector{Float64}, refLLA::LLA=LLA(mean(lattitudes), mean(longitudes)); node_range::Number=100.0)
Create a spatial index for nodes
having lattitudes
and longitudes
using refLLA
as the reference for ENU coordinates with the given node_range
in meters.
NodeSpatIndex(nodes::AbstractVector{Int64}, llas::AbstractVector{LLA}, refLLA::LLA; node_range::Number=100.0)
Create a spatial index for nodes
having llas
LLA coordinates using refLLA
as the reference for ENU coordinates with the given node_range
in meters.
NodeSpatIndex(nodes::AbstractVector{Int64}, enus::AbstractVector{ENU}, refLLA::LLA; node_range::Number=100.0)
Create a spatial index for nodes
having enus
ENU coordinates using refLLA
as the reference for ENU coordinates with the given node_range
in meters.
OSMToolset.findnode
— Functionfindnode(sindex::NodeSpatIndex, point::Union{LLA, ENU})
Find the node in the sindex
spatial index closest to the given point
coordinates.
Returns a named tuple of the distance
and the nodeid
. When no node is found within the node_range
of sindex
the nodeid
is set to 0
and the distance
to Inf
.
OSMToolset.calc_tiling
— Methodcalc_tiling(filename::AbstractString, latTileSize::Float64, lonTileSize::Float64)
Calculates recommended bounds, number of rows and columns for a given filename
and size of tile latTileSize
x lonTileSize
.
OSMToolset.calc_tiling
— Methodcalc_tiling(bounds::Bounds, latTileSize::Float64, lonTileSize::Float64)
Calculates recommended bounds, number of rows and columns for a given bounds
and size of tile latTileSize
x lonTileSize
.
OSMToolset.tile_osm_file
— Methodtile_osm_file(filename::AbstractString, [bounds::Bounds]; nrow::Integer, ncol::Integer, [out_dir::AbstractString]
Provide the tiling functionality for maps. A filename
will be open for processing and the tiling will be done around given bounds
. If bounds
are not given they will be calculated using getbounds
function. The tiling will be performed with a matrix having nrow
rows and ncol
columns. The output will be written to the folder name out_dir
. If none out_dir
is given than as the output is written to where filename
is located.
Returns a Matrix{String}
of size nrow
x ncol
containing the names of the files created.
OSMToolset.Bounds
— TypeA range of geographic coordinates for a map
OSMToolset.getbounds
— Methodgetbounds(filename::AbstractString)::Bounds
Returns Bounds that can be found in the first 10 lines of the OSM file named 'filename'
Helper functions
OSMToolset.sample_osm_file
— FunctionProvides location of sample OSM file for tests
OSMToolset.FloatLon
— TypeThis is an AbstractFloat type representing geographic longitude as the values may wrap around
OSMToolset.Node
— TypeNode
+Reference · OSMToolset Reference
Scraping points-of-interest (POI)
OSMToolset.find_poi
— Functionfind_poi(filename::AbstractString; scrape_config::ScrapePOIConfig{T <: MetaPOI}=__builtin_poiconfig)
Generates a DataFrame
with points of interests and from a given XML filename
. The data frame will also contain the metadata from T
for each POI.
The DataFrame
can be later used with AttractivenessSpatIndex
to build an attractivenss spatial index.
The attractiveness values for the index will be used ones from the scrape_config
file. By default __builtin_poiconfig
from __builtin_config_path
will be used but you can define your own index.
sourceOSMToolset.ScrapePOIConfig
— TypeRepresents the configuration of the data scraping process from OSM XML.
Only those pieces of data will be scraped that are defined here.
The configuration is defined in a DataFrame with the following columns: group
, key
, values
, influence
, range
. Instead of the DataFrame a paths to a CSV file can be provided.
- Constructors *
ScrapePOIConfig()
- default inbuilt configuration for data scraping. Note that the default configuration can change with library updates. This will use AttractivenessMetaPOI
as meta data.ScrapePOIConfig{T <: MetaPOI}(filename::AbstractString)
- use a CSV file with configurationScrapePOIConfig{T <: MetaPOI}(df::DataFrame)
- use a DataFrame
When the T
parameter is not provided AttractivenessMetaPOI
will be used. When you do not want to use metadata provide NoneMetaPOI
as T
sourceOSMToolset.MetaPOI
— Typeabstract type MetaPOI end
A base time for representing metadata related to a POI location.
sourceOSMToolset.NoneMetaPOI
— Typestruct NoneMetaPOI <: MetaPOI; end
A subtype of MetaPOI
that does not contain any metadata.
sourceOSMToolset.AttractivenessMetaPOI
— Typestruct AttractivenessMetaPOI <: MetaPOI
A subtype of MetaPOI
that contains metadata for attractiveness (the default configuration of scraping). This assumes that the metadata is stored in a CSV file with the following columns: key
, values
, group
, influence
, range
.
sourceMeasuring Attractiveness Spatial Index
OSMToolset.AttractivenessSpatIndex
— TypeAttractivenessSpatIndex{T <: MetaPOI}(filename::AbstractString, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)
+AttractivenessSpatIndex{T <: MetaPOI}(df::AbstractDataFrame, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)
Builds an attractivness spatial index basing on data in some CSV file or a DataFrame
Assuming that T
is of typw AttractivenessMetaPOI
, the CSV file or DataFrame should have the following columns: - group - data group in attractiveness index, each group name creates attractiveness dimension - key - key in the XML file <tag> - values - values in the <tag> (a star "*"
catches all values) - influence - strength of influence - range - maximum influence range in meters
When a DataFrame
is provided the additional parameter refLLA
can be provided for the reference LLA
coordinates in the spatial index. The spatial index works in the ENU coordinate system.
If T
is not provided AttractivenessMetaPOI
will be used as the default metadata type.
The type F
represents the attractiveness group function provided as get_group = (a::T) -> :somegroup
.
sourceOSMToolset.attractiveness
— Functionattractiveness(sindex::AttractivenessSpatIndex{T}, lattitude::Number, longitude::Number; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI
Returns the multidimensional attractiveness measure for the given spatial index sindex
and lattitude
and longitude
. The aggregator
function will be used to aggregate the attractiveness values. The aggreagation is required as more than one point of interest can be found within the attractiveness range. The function calculate_attractiveness(a::T, poidistance::Number)
will be used to calculate the attractiveness on the base of metadata and distance. The distance function distance(a::ENU, b::ENU)
is used to calculate the distance between point pairs.
If explain
is set to true the result will additionally contain details about POIs used to calculate the attractiveness.
sourceattractiveness(sindex::AttractivenessSpatIndex{T}, lla::LLA; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI
Returns the multidimensional attractiveness measure for the given spatial index sindex
and LLA
coordinates. The aggregator
function will be used to aggregate the attractiveness values. The aggreagation is required as more than one point of interest can be found within the attractiveness range. The function calculate_attractiveness(a::T, poidistance::Number)
will be used to calculate the attractiveness on the base of metadata and distance. The distance function distance(a::ENU, b::ENU)
is used to calculate the distance between point pairs.
If explain
is set to true the result will additionally contain details about POIs used to calculate the attractiveness.
sourceattractiveness(sindex::AttractivenessSpatIndex{T}, enu::ENU; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI
Returns the multidimensional attractiveness measure for the given spatial index sindex
and enu
cooridanates. Note that the enu coordinates must use sindex.refLLA
as the reference point. Hence the enu
coordinates need to be calculated eg. using ENU(lla,sindex.refLLA)
. The aggregator
function will be used to aggregate the attractiveness values. The aggreagation is required as more than one point of interest can be found within the attractiveness range. The function calculate_attractiveness(a::T, poidistance::Number)
will be used to calculate the attractiveness on the base of metadata and distance. The distance function distance(a::ENU, b::ENU)
is used to calculate the distance between point pairs.
If explain
is set to true the result will additionally contain details about POIs used to calculate the attractiveness.
sourceOSMToolset.calculate_attractiveness
— Functioncalculate_attractiveness(a::AttractivenessMetaPOI, poidistance::Number)
Default function used to calculate the attractiveness for AttractivenessMetaPOI
on the base of distance. You might want to provide your own implementation and than pass it as a parameter whe using the attractiveness
function.
sourceOSMToolset.get_attractiveness_group
— Functionget_attractiveness_group(a::AttractivenessMetaPOI)
Default group for AttractivenessMetaPOI which is a.group
.
sourceget_attractiveness_group(a::NoneMetaPOI)
Default group for NoneMetaPOI (NoneMetaPOI
).
sourceOSMToolset.clean_pois_by_group
— Functionclean_pois_by_group(df::DataFrame)
For data imported via AttractivenessMetaPOI the function will return only the most attractive POI for each group. This is useful when you want to remove duplicate entries for the same node.
sourceEfficient searching for nearest nodes in OSM
OSMToolset.NodeSpatIndex
— TypeNodeSpatIndex(md::MapData, refLLA::LLA = OpenStreetMapX.center(md.bounds); node_range::Number=100.0)
Create a spatial index for nodes in the md
using refLLA
as the reference for ENU coordinates with the given node_range
in meters.
sourceNodeSpatIndex(nodes::AbstractVector{Int64}, lattitudes::AbstractVector{Float64}, longitudes::AbstractVector{Float64}, refLLA::LLA=LLA(mean(lattitudes), mean(longitudes)); node_range::Number=100.0)
Create a spatial index for nodes
having lattitudes
and longitudes
using refLLA
as the reference for ENU coordinates with the given node_range
in meters.
sourceNodeSpatIndex(nodes::AbstractVector{Int64}, llas::AbstractVector{LLA}, refLLA::LLA; node_range::Number=100.0)
Create a spatial index for nodes
having llas
LLA coordinates using refLLA
as the reference for ENU coordinates with the given node_range
in meters.
sourceNodeSpatIndex(nodes::AbstractVector{Int64}, enus::AbstractVector{ENU}, refLLA::LLA; node_range::Number=100.0)
Create a spatial index for nodes
having enus
ENU coordinates using refLLA
as the reference for ENU coordinates with the given node_range
in meters.
sourceOSMToolset.findnode
— Functionfindnode(sindex::NodeSpatIndex, point::Union{LLA, ENU})
Find the node in the sindex
spatial index closest to the given point
coordinates.
Returns a named tuple of the distance
and the nodeid
. When no node is found within the node_range
of sindex
the nodeid
is set to 0
and the distance
to Inf
.
sourceTiling OSM file
OSMToolset.calc_tiling
— Methodcalc_tiling(filename::AbstractString, latTileSize::Float64, lonTileSize::Float64)
Calculates recommended bounds, number of rows and columns for a given filename
and size of tile latTileSize
x lonTileSize
.
sourceOSMToolset.calc_tiling
— Methodcalc_tiling(bounds::Bounds, latTileSize::Float64, lonTileSize::Float64)
Calculates recommended bounds, number of rows and columns for a given bounds
and size of tile latTileSize
x lonTileSize
.
sourceOSMToolset.tile_osm_file
— Methodtile_osm_file(filename::AbstractString, [bounds::Bounds]; nrow::Integer, ncol::Integer, [out_dir::AbstractString]
Provide the tiling functionality for maps. A filename
will be open for processing and the tiling will be done around given bounds
. If bounds
are not given they will be calculated using getbounds
function. The tiling will be performed with a matrix having nrow
rows and ncol
columns. The output will be written to the folder name out_dir
. If none out_dir
is given than as the output is written to where filename
is located.
Returns a Matrix{String}
of size nrow
x ncol
containing the names of the files created.
sourceOSMToolset.Bounds
— TypeA range of geographic coordinates for a map
sourceOSMToolset.getbounds
— Methodgetbounds(filename::AbstractString)::Bounds
Returns Bounds that can be found in the first 10 lines of the OSM file named 'filename'
sourceHelper functions
OSMToolset.sample_osm_file
— FunctionProvides location of sample OSM file for tests
sourceOSMToolset.FloatLon
— TypeThis is an AbstractFloat type representing geographic longitude as the values may wrap around
sourceOSMToolset.Node
— TypeNode
A node is a point in the map. It has an id, a latitude and a longitude.
-All nodes need to be stored in memory in this format.
sourceSettings
This document was generated with Documenter.jl version 1.1.2 on Tuesday 31 October 2023. Using Julia version 1.9.3.
+All nodes need to be stored in memory in this format.
Settings
This document was generated with Documenter.jl version 1.1.2 on Tuesday 31 October 2023. Using Julia version 1.9.3.
Settings
This document was generated with Documenter.jl version 1.1.2 on Tuesday 31 October 2023. Using Julia version 1.9.3.