diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 82f111e..72554f0 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-24T09:58:56","documenter_version":"1.5.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-24T10:02:22","documenter_version":"1.5.0"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index abe8988..b32734f 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · OSMToolset
+Home · OSMToolset
diff --git a/dev/objects.inv b/dev/objects.inv index 2a97221..4850524 100644 Binary files a/dev/objects.inv and b/dev/objects.inv differ diff --git a/dev/reference/index.html b/dev/reference/index.html index cc53376..5394bc6 100644 --- a/dev/reference/index.html +++ b/dev/reference/index.html @@ -1,3 +1,3 @@ -Reference · OSMToolset

Reference

Scraping points-of-interest (POI)

OSMToolset.find_poiFunction
find_poi(filename::AbstractString, scrape_config::ScrapePOIConfig{T <: AbstractMetaPOI}=ScrapePOIConfig(); all_tags::Bool=false)

Generates a DataFrame with points of interests and from a given XML filename. The scrape_config parameter defines the configuration of the scraping process. The data frame will also contain the metadata of type T for each POI.

The DataFrame can be later used with AttractivenessSpatIndex to build an attractivenss spatial index.

Setting the all_tags parameter to true will cause that once the tag is matched, the adjacent tags within the same element will be included in the resulting DataFrame.

source
OSMToolset.ScrapePOIConfigType
Represents 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 a default configuration and AttractivenessMetaPOI as meta data.
  • ScrapePOIConfig(keys::Union{Tuple{String,String}, String}...) - provide keys for scraping, NoneMetaPOI will be used as metadata
  • ScrapePOIConfig(pairs::Pair{<:Union{Tuple{String,String}, String}, T}...) - provide keys and corresponding metadata
  • ScrapePOIConfig{T <: AbstractMetaPOI}(df::DataFrame) - use a DataFrame as configuration
  • ScrapePOIConfig{T <: AbstractMetaPOI}(meta::Dict{<:Union{String, Tuple{String,String}}, T}) - internal constructor. meta dictionary explaining how a single k="keyname" value or tuple ofvalues (paired with v="valuename") should be mapped for attractiveness metadata.

Example

```julia ScrapePOIConfig(("amenity", "parking"), ("parking"))

ScrapePOIConfig(("*", "restaurant"))

ScrapePOIConfig("*")

ScrapePOIConfig(("amenity", "parking") =>AttractivenessMetaPOI(:car, 1, 500), ("amenity", "restaurant") => (AttractivenessMetaPOI(:food, 1.0, 1000.0)))

ScrapePOIConfig([("amenity", "pub"), ("amenity", "restaurant")] .=> Ref(AttractivenessMetaPOI(:food, 1.0, 100.0)))

source
OSMToolset.NoneMetaPOIType
struct NoneMetaPOI <: AbstractMetaPOI; end

Scraping configuration when no attractiveness metadata is attached.

source
OSMToolset.AttractivenessMetaPOIType
struct AttractivenessMetaPOI <: AbstractMetaPOI

Container for metadata for attractiveness (the default configuration of scraping).

The attractiveness is defined by the following fields:

  • group - the group of the POI (e.g. :parking or :food)
  • influence - the power of the POI on the attractiveness of the location
  • range - the range of the POI influence (measeured in meters)
source

Measuring Attractiveness Spatial Index

OSMToolset.AttractivenessSpatIndexType
AttractivenessSpatIndex{T <: AbstractMetaPOI}(filename::AbstractString, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)
-AttractivenessSpatIndex{T <: AbstractMetaPOI}(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.

source
OSMToolset.attractivenessFunction
attractiveness(sindex::AttractivenessSpatIndex{T}, lattitude::Number, longitude::Number; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness,  distance::Function=OpenStreetMapX.distance, explain::Bool=false)  where T <: AbstractMetaPOI

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.

source
attractiveness(sindex::AttractivenessSpatIndex{T}, lla::LLA; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: AbstractMetaPOI

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.

source
attractiveness(sindex::AttractivenessSpatIndex{T}, enu::ENU; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: AbstractMetaPOI

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.

source
OSMToolset.calculate_attractivenessFunction
calculate_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.

source
OSMToolset.get_attractiveness_groupFunction
get_attractiveness_group(a::AttractivenessMetaPOI)

Default group for AttractivenessMetaPOI which is a.group.

source
get_attractiveness_group(a::NoneMetaPOI)

Default group for NoneMetaPOI (NoneMetaPOI).

source
OSMToolset.clean_pois_by_groupFunction
clean_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.

source

Efficient searching for nearest nodes in OSM

OSMToolset.NodeSpatIndexType
NodeSpatIndex(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.

source
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.

source
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.

source
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.

source
OSMToolset.findnodeFunction
findnode(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.

source

Tiling OSM file

OSMToolset.calc_tilingMethod
calc_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.

source
OSMToolset.calc_tilingMethod
calc_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.

source
OSMToolset.tile_osm_fileMethod
tile_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.

source
OSMToolset.getboundsMethod
getbounds(filename::AbstractString)::Bounds

Returns Bounds that can be found in the first 10 lines of the OSM file named 'filename'

source

Helper functions

OSMToolset.FloatLonType
This is an AbstractFloat type representing geographic longitude as the values may wrap around
source
OSMToolset.NodeType
Node(id::Int, lat::Float64, lon::Float64)

A node is a point in the map. It has an id, a latitude and a longitude.

source
+Reference · OSMToolset

Reference

Scraping points-of-interest (POI)

OSMToolset.find_poiFunction
find_poi(filename::AbstractString, scrape_config::ScrapePOIConfig{T <: AbstractMetaPOI}=ScrapePOIConfig(); all_tags::Bool=false)

Generates a DataFrame with points of interests and from a given XML filename. The scrape_config parameter defines the configuration of the scraping process. The data frame will also contain the metadata of type T for each POI.

The DataFrame can be later used with AttractivenessSpatIndex to build an attractivenss spatial index.

Setting the all_tags parameter to true will cause that once the tag is matched, the adjacent tags within the same element will be included in the resulting DataFrame.

source
OSMToolset.ScrapePOIConfigType
Represents 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 a default configuration and AttractivenessMetaPOI as meta data.
  • ScrapePOIConfig(keys::Union{Tuple{String,String}, String}...) - provide keys for scraping, NoneMetaPOI will be used as metadata
  • ScrapePOIConfig(pairs::Pair{<:Union{Tuple{String,String}, String}, T}...) - provide keys and corresponding metadata
  • ScrapePOIConfig{T <: AbstractMetaPOI}(df::DataFrame) - use a DataFrame as configuration
  • ScrapePOIConfig{T <: AbstractMetaPOI}(meta::Dict{<:Union{String, Tuple{String,String}}, T}) - internal constructor. meta dictionary explaining how a single k="keyname" value or tuple ofvalues (paired with v="valuename") should be mapped for attractiveness metadata.

Example

```julia ScrapePOIConfig(("amenity", "parking"), ("parking"))

ScrapePOIConfig(("*", "restaurant"))

ScrapePOIConfig("*")

ScrapePOIConfig(("amenity", "parking") =>AttractivenessMetaPOI(:car, 1, 500), ("amenity", "restaurant") => (AttractivenessMetaPOI(:food, 1.0, 1000.0)))

ScrapePOIConfig([("amenity", "pub"), ("amenity", "restaurant")] .=> Ref(AttractivenessMetaPOI(:food, 1.0, 100.0)))

source
OSMToolset.NoneMetaPOIType
struct NoneMetaPOI <: AbstractMetaPOI; end

Scraping configuration when no attractiveness metadata is attached.

source
OSMToolset.AttractivenessMetaPOIType
struct AttractivenessMetaPOI <: AbstractMetaPOI

Container for metadata for attractiveness (the default configuration of scraping).

The attractiveness is defined by the following fields:

  • group - the group of the POI (e.g. :parking or :food)
  • influence - the power of the POI on the attractiveness of the location
  • range - the range of the POI influence (measeured in meters)
source

Measuring Attractiveness Spatial Index

OSMToolset.AttractivenessSpatIndexType
AttractivenessSpatIndex{T <: AbstractMetaPOI}(filename::AbstractString, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)
+AttractivenessSpatIndex{T <: AbstractMetaPOI}(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.

source
OSMToolset.attractivenessFunction
attractiveness(sindex::AttractivenessSpatIndex{T}, lattitude::Number, longitude::Number; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness,  distance::Function=OpenStreetMapX.distance, explain::Bool=false)  where T <: AbstractMetaPOI

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.

source
attractiveness(sindex::AttractivenessSpatIndex{T}, lla::LLA; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: AbstractMetaPOI

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.

source
attractiveness(sindex::AttractivenessSpatIndex{T}, enu::ENU; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: AbstractMetaPOI

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.

source
OSMToolset.calculate_attractivenessFunction
calculate_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.

source
OSMToolset.get_attractiveness_groupFunction
get_attractiveness_group(a::AttractivenessMetaPOI)

Default group for AttractivenessMetaPOI which is a.group.

source
get_attractiveness_group(a::NoneMetaPOI)

Default group for NoneMetaPOI (NoneMetaPOI).

source
OSMToolset.clean_pois_by_groupFunction
clean_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.

source

Efficient searching for nearest nodes in OSM

OSMToolset.NodeSpatIndexType
NodeSpatIndex(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.

source
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.

source
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.

source
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.

source
OSMToolset.findnodeFunction
findnode(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.

source

Tiling OSM file

OSMToolset.calc_tilingMethod
calc_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.

source
OSMToolset.calc_tilingMethod
calc_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.

source
OSMToolset.tile_osm_fileMethod
tile_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.

source
OSMToolset.getboundsMethod
getbounds(filename::AbstractString)::Bounds

Returns Bounds that can be found in the first 10 lines of the OSM file named 'filename'

source

Helper functions

OSMToolset.FloatLonType
This is an AbstractFloat type representing geographic longitude as the values may wrap around
source
OSMToolset.NodeType
Node(id::Int, lat::Float64, lon::Float64)

A node is a point in the map. It has an id, a latitude and a longitude.

source
diff --git a/dev/visualize/index.html b/dev/visualize/index.html index d2c9cae..4273bc6 100644 --- a/dev/visualize/index.html +++ b/dev/visualize/index.html @@ -95,4 +95,4 @@ attdf = getplotdata(md, dfpoi) -scatter!(plotmap(md), attdf.x, attdf.y;zcolor=attdf.att, legend=false, colorbar=true, markershape=:rect, markeralpha=0.32,markerstrokewidth=0,markersize=3.45, colorbar_title="restaurant/cafe walkability index")

POI Visualization

+scatter!(plotmap(md), attdf.x, attdf.y;zcolor=attdf.att, legend=false, colorbar=true, markershape=:rect, markeralpha=0.32,markerstrokewidth=0,markersize=3.45, colorbar_title="restaurant/cafe walkability index")

POI Visualization