diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index f22a469..0d6abd6 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-31T16:29:45","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-31T16:49:04","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index 6aa5d3c..9fda450 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · OSMToolset
GitHub
+Home · OSMToolset
GitHub
diff --git a/dev/reference/index.html b/dev/reference/index.html index e4d1055..9980110 100644 --- a/dev/reference/index.html +++ b/dev/reference/index.html @@ -1,6 +1,6 @@ -Reference · OSMToolset
GitHub

Reference

Scraping points-of-interest (POI)

OSMToolset.find_poi — Function
find_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.

source
OSMToolset.ScrapePOIConfig — Type
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 AttractivenessMetaPOI as meta data.
  • ScrapePOIConfig{T <: MetaPOI}(filename::AbstractString) - use a CSV file with configuration
  • ScrapePOIConfig{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

source
OSMToolset.MetaPOI — Type
abstract type MetaPOI end

A base time for representing metadata related to a POI location.

source
OSMToolset.AttractivenessMetaPOI — Type
struct 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.

source

Measuring Attractiveness Spatial Index

OSMToolset.AttractivenessSpatIndex — Type
AttractivenessSpatIndex{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.

source
OSMToolset.attractiveness — Function
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 <: 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.

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

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

source
OSMToolset.calculate_attractiveness — Function
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_group — Function
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_group — Function
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.NodeSpatIndex — Type
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.findnode — Function
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_tiling — Method
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_tiling — Method
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_file — Method
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.getbounds — Method
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.FloatLon — Type
This is an AbstractFloat type representing geographic longitude as the values may wrap around
source
OSMToolset.Node — Type
Node
+Reference · OSMToolset
GitHub
Reference
Scraping points-of-interest (POI)
OSMToolset.find_poi — Function
find_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.
source
OSMToolset.ScrapePOIConfig — Type
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 AttractivenessMetaPOI as meta data.
  • ScrapePOIConfig{T <: MetaPOI}(filename::AbstractString) - use a CSV file with configuration
  • ScrapePOIConfig{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
source
OSMToolset.MetaPOI — Type
abstract type MetaPOI end
A base time for representing metadata related to a POI location.
source
OSMToolset.AttractivenessMetaPOI — Type
struct 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.
source
Measuring Attractiveness Spatial Index
OSMToolset.AttractivenessSpatIndex — Type
AttractivenessSpatIndex{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.
source
OSMToolset.attractiveness — Function
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 <: 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.
source
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.
source
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.
source
OSMToolset.calculate_attractiveness — Function
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_group — Function
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_group — Function
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.NodeSpatIndex — Type
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.findnode — Function
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_tiling — Method
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_tiling — Method
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_file — Method
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.getbounds — Method
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.FloatLon — Type
This is an AbstractFloat type representing geographic longitude as the values may wrap around
source
OSMToolset.Node — Type
Node
 
 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.
source

+All nodes need to be stored in memory in this format.
source
diff --git a/dev/search_index.js b/dev/search_index.js index 7b4621a..360808b 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"visualize/#Visualization","page":"Visualization","title":"Visualization","text":"","category":"section"},{"location":"visualize/#How-to-visualize-the-data","page":"Visualization","title":"How to visualize the data","text":"","category":"section"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"The library can be integrated with various vizualisation frameworks. Below we show two example codes that can be a base for further exploration. The first example uses folium via PyCall while the second example uses Plots.jl combined with OpenStreetMapXPlot.jl.","category":"page"},{"location":"visualize/#Point-of-interest-with-Python-folium-via-PyCall","page":"Visualization","title":"Point of interest with Python folium via PyCall","text":"","category":"section"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"Below is a sample piece of code that can be used to generate a visualization of POIs on a map.","category":"page"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"using PyCall\nusing Colors\nusing OSMToolset\n\nfile = sample_osm_file()\ndf = find_poi(file)\nix = AttractivenessSpatIndex(df);\n\nflm = pyimport(\"folium\");\n\ncolrs = distinguishable_colors(length(ix.measures), [RGB(0.1,0.2,0.4)])\nclass2col = Dict(ix.measures .=> colrs);\n\nm = flm.Map(tiles = \"Stamen Toner\")\nline = 0\n\nfor row in eachrow(df)\n line += 1\n info = \"$(row.group):$(row.key)=$(row.value)\"\n\n k = findfirst(==(Symbol(row.group)), ix.measures)\n flm.Circle((row.lat, row.lon), color=\"#$(hex(colrs[k]))\",radius=row.influence,\n fill_color=\"#$(hex(colrs[k]))\", fill_opacity=0.06, tooltip=info).add_to(m)\n\nend\nbb = getbounds(file)\nbounds = [(bb.minlat, Float64(bb.minlon)), (bb.maxlat, Float64(bb.maxlon))]\nm.fit_bounds(bounds)\nflm.Rectangle(bounds, color=\"blue\",weight=2).add_to(m)\n\nm","category":"page"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"The obtained result should be similar to the picture below.","category":"page"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"(Image: POI Visualization)","category":"page"},{"location":"visualize/#Buidling-walkability-index-and-vizualisation-with-OpenStreetMapX","page":"Visualization","title":"Buidling walkability index and vizualisation with OpenStreetMapX","text":"","category":"section"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"using Pkg\nusing OSMToolset\nusing DataFrames\nusing Plots\nusing OpenStreetMapX, OpenStreetMapXPlot\n\n# downloading a fragment of Boston map from the Overpass API\nf = download(\"https://overpass-api.de/api/map?bbox=-71.0912,42.3550,-71.0486,42.3751\")\nmv(f, \"Boston.osm\")\n\n\"\"\" Prepares data for plotting for a given map data ams set of POIs \"\"\"\nfunction getplotdata(md, dfpoi)\n\n # All ENU coordinates should have the same reference point\n refLLA = OpenStreetMapX.center(md.bounds)\n\n enus = ENU.(LLA.(dfpoi.lat, dfpoi.lon), Ref(refLLA))\n x = getX.(enus)\n minx, maxx = minimum(x), maximum(x)\n y = getY.(enus)\n miny, maxy = minimum(y), maximum(y)\n\n\n # index for efficient spatial queries for nodes\n ixnodes = NodeSpatIndex(md, refLLA; node_range=150.0)\n\n # index for efficient spatial queries for poi availability\n # pois further than 350m are not considered\n ixpoi = AttractivenessSpatIndex{NoneMetaPOI}(dfpoi, refLLA; get_range=a->350, get_group=a->:poi);\n\n \"\"\" Calcylated a distance between a given coordinate and a POI \"\"\"\n function mydistance(enu1, enu2)\n OpenStreetMapX.distance(enu1, enu2) > 700 && return Inf\n dist1, node1 = findnode(ixnodes, LLA(enu1, refLLA))\n dist2, node2 = findnode(ixnodes, LLA(enu2, refLLA))\n if dist1 > 150 || dist2 > 350 # points off the road grid\n return Inf\n end\n dist1 + OpenStreetMapX.shortest_route(md, node1, node2)[2] + dist2\n end\n\n\n cellsize = 50 # size of a box in meters\n attdf = DataFrame()\n\n lock = Threads.ReentrantLock()\n Threads.@threads for i in 0:round(Int, (xmax - xmin) / cellsize)\n for j in 0:round(Int, (ymax - ymin) / cellsize)\n enu = ENU(xmin + i*cellsize, ymin + j*cellsize)\n att = attractiveness(ixpoi, enu; distance=mydistance,\n calculate_attractiveness=(_, poidist) -> max(0.0, (750 - poidist) / 750))\n if att.poi > 0\n Threads.lock(lock) do\n push!(attdf,(;x=getX(enu), y=getY(enu), att=att.poi))\n end\n end\n end\n end\n return attdf\nend\n\nmd = get_map_data(\"Boston.osm\"; use_cache=false, only_intersections=false);\nconfig = DataFrame(key=\"amenity\", values=[\"restaurant\", \"fast_food\", \"food_court\", \"pub\", \"bar\", \"cafe\", \"ice_cream\"])\ndfpoi = find_poi(\"Boston.osm\"; scrape_config=ScrapePOIConfig{NoneMetaPOI}(config))\n\n\nattdf = getplotdata(md, dfpoi)\n\nscatter!(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\")","category":"page"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"(Image: POI Visualization)","category":"page"},{"location":"reference/#Reference","page":"Reference","title":"Reference","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"CurrentModule = OSMToolset\nDocTestSetup = quote\n using OSMToolset\nend","category":"page"},{"location":"reference/#Scraping-points-of-interest-(POI)","page":"Reference","title":"Scraping points-of-interest (POI)","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"find_poi\nScrapePOIConfig\nMetaPOI\nNoneMetaPOI\nAttractivenessMetaPOI","category":"page"},{"location":"reference/#OSMToolset.find_poi","page":"Reference","title":"OSMToolset.find_poi","text":"find_poi(filename::AbstractString; scrape_config::ScrapePOIConfig{T <: MetaPOI}=__builtin_poiconfig)\n\nGenerates 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.\n\nThe DataFrame can be later used with AttractivenessSpatIndex to build an attractivenss spatial index.\n\nThe 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.\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.ScrapePOIConfig","page":"Reference","title":"OSMToolset.ScrapePOIConfig","text":"Represents the configuration of the data scraping process from OSM XML.\n\nOnly those pieces of data will be scraped that are defined here.\n\nThe 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.\n\nConstructors *\nScrapePOIConfig() - default inbuilt configuration for data scraping. Note that the default configuration can change with library updates. This will use AttractivenessMetaPOI as meta data.\nScrapePOIConfig{T <: MetaPOI}(filename::AbstractString) - use a CSV file with configuration\nScrapePOIConfig{T <: MetaPOI}(df::DataFrame) - use a DataFrame\n\nWhen the T parameter is not provided AttractivenessMetaPOI will be used. When you do not want to use metadata provide NoneMetaPOI as T\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.MetaPOI","page":"Reference","title":"OSMToolset.MetaPOI","text":"abstract type MetaPOI end\n\nA base time for representing metadata related to a POI location.\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.NoneMetaPOI","page":"Reference","title":"OSMToolset.NoneMetaPOI","text":"struct NoneMetaPOI <: MetaPOI; end\n\nA subtype of MetaPOI that does not contain any metadata.\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.AttractivenessMetaPOI","page":"Reference","title":"OSMToolset.AttractivenessMetaPOI","text":"struct AttractivenessMetaPOI <: MetaPOI\n\nA 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.\n\n\n\n\n\n","category":"type"},{"location":"reference/#Measuring-Attractiveness-Spatial-Index","page":"Reference","title":"Measuring Attractiveness Spatial Index","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"AttractivenessSpatIndex\nattractiveness\ncalculate_attractiveness\nget_attractiveness_group\nclean_pois_by_group","category":"page"},{"location":"reference/#OSMToolset.AttractivenessSpatIndex","page":"Reference","title":"OSMToolset.AttractivenessSpatIndex","text":"AttractivenessSpatIndex{T <: MetaPOI}(filename::AbstractString, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)\nAttractivenessSpatIndex{T <: MetaPOI}(df::AbstractDataFrame, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)\n\nBuilds an attractivness spatial index basing on data in some CSV file or a DataFrame\n\nAssuming 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 - values - values in the (a star \"*\" catches all values) - influence - strength of influence - range - maximum influence range in meters\n\nWhen 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.\n\nIf T is not provided AttractivenessMetaPOI will be used as the default metadata type.\n\nThe type F represents the attractiveness group function provided as get_group = (a::T) -> :somegroup.\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.attractiveness","page":"Reference","title":"OSMToolset.attractiveness","text":"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 <: MetaPOI\n\nReturns 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.\n\nIf explain is set to true the result will additionally contain details about POIs used to calculate the attractiveness.\n\n\n\n\n\nattractiveness(sindex::AttractivenessSpatIndex{T}, lla::LLA; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI\n\nReturns 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.\n\nIf explain is set to true the result will additionally contain details about POIs used to calculate the attractiveness.\n\n\n\n\n\nattractiveness(sindex::AttractivenessSpatIndex{T}, enu::ENU; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI\n\nReturns 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.\n\nIf explain is set to true the result will additionally contain details about POIs used to calculate the attractiveness.\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.calculate_attractiveness","page":"Reference","title":"OSMToolset.calculate_attractiveness","text":"calculate_attractiveness(a::AttractivenessMetaPOI, poidistance::Number)\n\nDefault 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.\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.get_attractiveness_group","page":"Reference","title":"OSMToolset.get_attractiveness_group","text":"get_attractiveness_group(a::AttractivenessMetaPOI)\n\nDefault group for AttractivenessMetaPOI which is a.group.\n\n\n\n\n\nget_attractiveness_group(a::NoneMetaPOI)\n\nDefault group for NoneMetaPOI (NoneMetaPOI).\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.clean_pois_by_group","page":"Reference","title":"OSMToolset.clean_pois_by_group","text":"clean_pois_by_group(df::DataFrame)\n\nFor 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.\n\n\n\n\n\n","category":"function"},{"location":"reference/#Efficient-searching-for-nearest-nodes-in-OSM","page":"Reference","title":"Efficient searching for nearest nodes in OSM","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"NodeSpatIndex\nfindnode","category":"page"},{"location":"reference/#OSMToolset.NodeSpatIndex","page":"Reference","title":"OSMToolset.NodeSpatIndex","text":"NodeSpatIndex(md::MapData, refLLA::LLA = OpenStreetMapX.center(md.bounds); node_range::Number=100.0)\n\nCreate a spatial index for nodes in the md using refLLA as the reference for ENU coordinates with the given node_range in meters.\n\n\n\n\n\nNodeSpatIndex(nodes::AbstractVector{Int64}, lattitudes::AbstractVector{Float64}, longitudes::AbstractVector{Float64}, refLLA::LLA=LLA(mean(lattitudes), mean(longitudes)); node_range::Number=100.0)\n\nCreate a spatial index for nodes having lattitudes and longitudes using refLLA as the reference for ENU coordinates with the given node_range in meters.\n\n\n\n\n\nNodeSpatIndex(nodes::AbstractVector{Int64}, llas::AbstractVector{LLA}, refLLA::LLA; node_range::Number=100.0)\n\nCreate a spatial index for nodes having llas LLA coordinates using refLLA as the reference for ENU coordinates with the given node_range in meters.\n\n\n\n\n\nNodeSpatIndex(nodes::AbstractVector{Int64}, enus::AbstractVector{ENU}, refLLA::LLA; node_range::Number=100.0)\n\nCreate a spatial index for nodes having enus ENU coordinates using refLLA as the reference for ENU coordinates with the given node_range in meters.\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.findnode","page":"Reference","title":"OSMToolset.findnode","text":"findnode(sindex::NodeSpatIndex, point::Union{LLA, ENU})\n\nFind the node in the sindex spatial index closest to the given point coordinates.\n\nReturns 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.\n\n\n\n\n\n","category":"function"},{"location":"reference/#Tiling-OSM-file","page":"Reference","title":"Tiling OSM file","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"calc_tiling(::AbstractString, ::Float64, ::Float64)\ncalc_tiling(::OSMToolset.Bounds, ::Float64, ::Float64)\ntile_osm_file(::AbstractString, ::Bounds; ::Integer, ::Integer, ::AbstractString)\nBounds\ngetbounds(::AbstractString)","category":"page"},{"location":"reference/#OSMToolset.calc_tiling-Tuple{AbstractString, Float64, Float64}","page":"Reference","title":"OSMToolset.calc_tiling","text":"calc_tiling(filename::AbstractString, latTileSize::Float64, lonTileSize::Float64)\n\nCalculates recommended bounds, number of rows and columns for a given filename and size of tile latTileSize x lonTileSize.\n\n\n\n\n\n","category":"method"},{"location":"reference/#OSMToolset.calc_tiling-Tuple{Bounds, Float64, Float64}","page":"Reference","title":"OSMToolset.calc_tiling","text":"calc_tiling(bounds::Bounds, latTileSize::Float64, lonTileSize::Float64)\n\nCalculates recommended bounds, number of rows and columns for a given bounds and size of tile latTileSize x lonTileSize.\n\n\n\n\n\n","category":"method"},{"location":"reference/#OSMToolset.tile_osm_file-Tuple{AbstractString, Bounds}","page":"Reference","title":"OSMToolset.tile_osm_file","text":"tile_osm_file(filename::AbstractString, [bounds::Bounds]; nrow::Integer, ncol::Integer, [out_dir::AbstractString]\n\nProvide 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.\n\nReturns a Matrix{String} of size nrow x ncol containing the names of the files created.\n\n\n\n\n\n","category":"method"},{"location":"reference/#OSMToolset.Bounds","page":"Reference","title":"OSMToolset.Bounds","text":"A range of geographic coordinates for a map\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.getbounds-Tuple{AbstractString}","page":"Reference","title":"OSMToolset.getbounds","text":"getbounds(filename::AbstractString)::Bounds\n\nReturns Bounds that can be found in the first 10 lines of the OSM file named 'filename'\n\n\n\n\n\n","category":"method"},{"location":"reference/","page":"Reference","title":"Reference","text":"Helper functions","category":"page"},{"location":"reference/","page":"Reference","title":"Reference","text":"sample_osm_file\nFloatLon\nOSMToolset.Node","category":"page"},{"location":"reference/#OSMToolset.sample_osm_file","page":"Reference","title":"OSMToolset.sample_osm_file","text":"Provides location of sample OSM file for tests\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.FloatLon","page":"Reference","title":"OSMToolset.FloatLon","text":"This is an AbstractFloat type representing geographic longitude as the values may wrap around\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.Node","page":"Reference","title":"OSMToolset.Node","text":"Node\n\nA node is a point in the map. It has an id, a latitude and a longitude.\nAll nodes need to be stored in memory in this format.\n\n\n\n\n\n","category":"type"},{"location":"","page":"Home","title":"Home","text":"CurrentModule = OSMToolset","category":"page"},{"location":"#OSMToolset.jl","page":"Home","title":"OSMToolset.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Documentation for OSMToolset.jl","category":"page"},{"location":"","page":"Home","title":"Home","text":"For details please go to the Reference section.","category":"page"},{"location":"","page":"Home","title":"Home","text":"There is also a Visualization example.","category":"page"},{"location":"#Aknowledgments","page":"Home","title":"Aknowledgments","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"This research was funded by National Science Centre, Poland grant number 2021/41/B/HS4/03349. ","category":"page"}] +[{"location":"visualize/#Visualization","page":"Visualization","title":"Visualization","text":"","category":"section"},{"location":"visualize/#How-to-visualize-the-data","page":"Visualization","title":"How to visualize the data","text":"","category":"section"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"The library can be integrated with various vizualisation frameworks. Below we show two example codes that can be a base for further exploration. The first example uses folium via PyCall while the second example uses Plots.jl combined with OpenStreetMapXPlot.jl.","category":"page"},{"location":"visualize/#Point-of-interest-with-Python-folium-via-PyCall","page":"Visualization","title":"Point of interest with Python folium via PyCall","text":"","category":"section"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"Below is a sample piece of code that can be used to generate a visualization of POIs on a map.","category":"page"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"using PyCall\nusing Colors\nusing OSMToolset\n\nfile = sample_osm_file()\ndf = find_poi(file)\nix = AttractivenessSpatIndex(df);\n\nflm = pyimport(\"folium\");\n\ncolrs = distinguishable_colors(length(ix.measures), [RGB(0.1,0.2,0.4)])\nclass2col = Dict(ix.measures .=> colrs);\n\nm = flm.Map(tiles = \"Stamen Toner\")\nline = 0\n\nfor row in eachrow(df)\n line += 1\n info = \"$(row.group):$(row.key)=$(row.value)\"\n\n k = findfirst(==(Symbol(row.group)), ix.measures)\n flm.Circle((row.lat, row.lon), color=\"#$(hex(colrs[k]))\",radius=row.influence,\n fill_color=\"#$(hex(colrs[k]))\", fill_opacity=0.06, tooltip=info).add_to(m)\n\nend\nbb = getbounds(file)\nbounds = [(bb.minlat, Float64(bb.minlon)), (bb.maxlat, Float64(bb.maxlon))]\nm.fit_bounds(bounds)\nflm.Rectangle(bounds, color=\"blue\",weight=2).add_to(m)\n\nm","category":"page"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"The obtained result should be similar to the picture below.","category":"page"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"(Image: POI Visualization)","category":"page"},{"location":"visualize/#Buidling-walkability-index-and-vizualisation-with-OpenStreetMapXPlot","page":"Visualization","title":"Buidling walkability index and vizualisation with OpenStreetMapXPlot","text":"","category":"section"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"In this example we download a map from the Overpass API. Next,","category":"page"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"using Pkg\nusing OSMToolset\nusing DataFrames\nusing Plots\nusing OpenStreetMapX, OpenStreetMapXPlot\n\n# downloading a fragment of Boston map from the Overpass API\nf = download(\"https://overpass-api.de/api/map?bbox=-71.0912,42.3550,-71.0486,42.3751\")\nmv(f, \"Boston.osm\")\n\n\"\"\" Prepares data for plotting for a given map data and a set of POIs \"\"\"\nfunction getplotdata(md, dfpoi)\n\n # All ENU coordinates should have the same reference point\n refLLA = OpenStreetMapX.center(md.bounds)\n\n enus = ENU.(LLA.(dfpoi.lat, dfpoi.lon), Ref(refLLA))\n x = getX.(enus)\n xmin, xmax = minimum(x), maximum(x)\n y = getY.(enus)\n ymin, ymax = minimum(y), maximum(y)\n\n\n # index for efficient spatial queries for nodes\n ixnodes = NodeSpatIndex(md, refLLA; node_range=150.0)\n\n # index for efficient spatial queries for poi availability\n # pois requiring a walk beyond 350m are not considered\n ixpoi = AttractivenessSpatIndex{NoneMetaPOI}(dfpoi, refLLA; get_range=a->350, get_group=a->:poi);\n\n \"\"\" Calculates the distance between a given coordinate and a POI location\"\"\"\n function mydistance(enu1, enu2)\n OpenStreetMapX.distance(enu1, enu2) > 700 && return Inf\n dist1, node1 = findnode(ixnodes, LLA(enu1, refLLA))\n dist2, node2 = findnode(ixnodes, LLA(enu2, refLLA))\n if dist1 > 150 || dist2 > 350 # points off the road grid\n return Inf\n end\n dist1 + OpenStreetMapX.shortest_route(md, node1, node2)[2] + dist2\n end\n\n cellsize = 50 # size of a box in meters\n attdf = DataFrame()\n\n # In order to speed-up the computations we parallelize this loop (run Julia with the -t paramater)\n lock = Threads.ReentrantLock()\n Threads.@threads for i in 0:round(Int, (xmax - xmin) / cellsize)\n for j in 0:round(Int, (ymax - ymin) / cellsize)\n enu = ENU(xmin + i*cellsize, ymin + j*cellsize)\n att = attractiveness(ixpoi, enu; distance=mydistance,\n calculate_attractiveness=(_, poidist) -> max(0.0, (750 - poidist) / 750))\n if att.poi > 0\n Threads.lock(lock) do\n push!(attdf,(;x=getX(enu), y=getY(enu), att=att.poi))\n end\n end\n end\n end\n return attdf\nend\n\nmd = get_map_data(\"Boston.osm\"; use_cache=false, only_intersections=false);\nconfig = DataFrame(key=\"amenity\", values=[\"restaurant\", \"fast_food\", \"food_court\", \"pub\", \"bar\", \"cafe\", \"ice_cream\"])\ndfpoi = find_poi(\"Boston.osm\"; scrape_config=ScrapePOIConfig{NoneMetaPOI}(config))\n\n\nattdf = getplotdata(md, dfpoi)\n\nscatter!(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\")","category":"page"},{"location":"visualize/","page":"Visualization","title":"Visualization","text":"(Image: POI Visualization)","category":"page"},{"location":"reference/#Reference","page":"Reference","title":"Reference","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"CurrentModule = OSMToolset\nDocTestSetup = quote\n using OSMToolset\nend","category":"page"},{"location":"reference/#Scraping-points-of-interest-(POI)","page":"Reference","title":"Scraping points-of-interest (POI)","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"find_poi\nScrapePOIConfig\nMetaPOI\nNoneMetaPOI\nAttractivenessMetaPOI","category":"page"},{"location":"reference/#OSMToolset.find_poi","page":"Reference","title":"OSMToolset.find_poi","text":"find_poi(filename::AbstractString; scrape_config::ScrapePOIConfig{T <: MetaPOI}=__builtin_poiconfig)\n\nGenerates 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.\n\nThe DataFrame can be later used with AttractivenessSpatIndex to build an attractivenss spatial index.\n\nThe 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.\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.ScrapePOIConfig","page":"Reference","title":"OSMToolset.ScrapePOIConfig","text":"Represents the configuration of the data scraping process from OSM XML.\n\nOnly those pieces of data will be scraped that are defined here.\n\nThe 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.\n\nConstructors *\nScrapePOIConfig() - default inbuilt configuration for data scraping. Note that the default configuration can change with library updates. This will use AttractivenessMetaPOI as meta data.\nScrapePOIConfig{T <: MetaPOI}(filename::AbstractString) - use a CSV file with configuration\nScrapePOIConfig{T <: MetaPOI}(df::DataFrame) - use a DataFrame\n\nWhen the T parameter is not provided AttractivenessMetaPOI will be used. When you do not want to use metadata provide NoneMetaPOI as T\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.MetaPOI","page":"Reference","title":"OSMToolset.MetaPOI","text":"abstract type MetaPOI end\n\nA base time for representing metadata related to a POI location.\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.NoneMetaPOI","page":"Reference","title":"OSMToolset.NoneMetaPOI","text":"struct NoneMetaPOI <: MetaPOI; end\n\nA subtype of MetaPOI that does not contain any metadata.\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.AttractivenessMetaPOI","page":"Reference","title":"OSMToolset.AttractivenessMetaPOI","text":"struct AttractivenessMetaPOI <: MetaPOI\n\nA 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.\n\n\n\n\n\n","category":"type"},{"location":"reference/#Measuring-Attractiveness-Spatial-Index","page":"Reference","title":"Measuring Attractiveness Spatial Index","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"AttractivenessSpatIndex\nattractiveness\ncalculate_attractiveness\nget_attractiveness_group\nclean_pois_by_group","category":"page"},{"location":"reference/#OSMToolset.AttractivenessSpatIndex","page":"Reference","title":"OSMToolset.AttractivenessSpatIndex","text":"AttractivenessSpatIndex{T <: MetaPOI}(filename::AbstractString, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)\nAttractivenessSpatIndex{T <: MetaPOI}(df::AbstractDataFrame, get_range::Function=get_attractiveness_range, get_group::Function=get_attractiveness_group)\n\nBuilds an attractivness spatial index basing on data in some CSV file or a DataFrame\n\nAssuming 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 - values - values in the (a star \"*\" catches all values) - influence - strength of influence - range - maximum influence range in meters\n\nWhen 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.\n\nIf T is not provided AttractivenessMetaPOI will be used as the default metadata type.\n\nThe type F represents the attractiveness group function provided as get_group = (a::T) -> :somegroup.\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.attractiveness","page":"Reference","title":"OSMToolset.attractiveness","text":"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 <: MetaPOI\n\nReturns 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.\n\nIf explain is set to true the result will additionally contain details about POIs used to calculate the attractiveness.\n\n\n\n\n\nattractiveness(sindex::AttractivenessSpatIndex{T}, lla::LLA; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI\n\nReturns 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.\n\nIf explain is set to true the result will additionally contain details about POIs used to calculate the attractiveness.\n\n\n\n\n\nattractiveness(sindex::AttractivenessSpatIndex{T}, enu::ENU; aggregator::Function=sum, calculate_attractiveness::Function=calculate_attractiveness, distance::Function=OpenStreetMapX.distance, explain::Bool=false) where T <: MetaPOI\n\nReturns 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.\n\nIf explain is set to true the result will additionally contain details about POIs used to calculate the attractiveness.\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.calculate_attractiveness","page":"Reference","title":"OSMToolset.calculate_attractiveness","text":"calculate_attractiveness(a::AttractivenessMetaPOI, poidistance::Number)\n\nDefault 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.\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.get_attractiveness_group","page":"Reference","title":"OSMToolset.get_attractiveness_group","text":"get_attractiveness_group(a::AttractivenessMetaPOI)\n\nDefault group for AttractivenessMetaPOI which is a.group.\n\n\n\n\n\nget_attractiveness_group(a::NoneMetaPOI)\n\nDefault group for NoneMetaPOI (NoneMetaPOI).\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.clean_pois_by_group","page":"Reference","title":"OSMToolset.clean_pois_by_group","text":"clean_pois_by_group(df::DataFrame)\n\nFor 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.\n\n\n\n\n\n","category":"function"},{"location":"reference/#Efficient-searching-for-nearest-nodes-in-OSM","page":"Reference","title":"Efficient searching for nearest nodes in OSM","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"NodeSpatIndex\nfindnode","category":"page"},{"location":"reference/#OSMToolset.NodeSpatIndex","page":"Reference","title":"OSMToolset.NodeSpatIndex","text":"NodeSpatIndex(md::MapData, refLLA::LLA = OpenStreetMapX.center(md.bounds); node_range::Number=100.0)\n\nCreate a spatial index for nodes in the md using refLLA as the reference for ENU coordinates with the given node_range in meters.\n\n\n\n\n\nNodeSpatIndex(nodes::AbstractVector{Int64}, lattitudes::AbstractVector{Float64}, longitudes::AbstractVector{Float64}, refLLA::LLA=LLA(mean(lattitudes), mean(longitudes)); node_range::Number=100.0)\n\nCreate a spatial index for nodes having lattitudes and longitudes using refLLA as the reference for ENU coordinates with the given node_range in meters.\n\n\n\n\n\nNodeSpatIndex(nodes::AbstractVector{Int64}, llas::AbstractVector{LLA}, refLLA::LLA; node_range::Number=100.0)\n\nCreate a spatial index for nodes having llas LLA coordinates using refLLA as the reference for ENU coordinates with the given node_range in meters.\n\n\n\n\n\nNodeSpatIndex(nodes::AbstractVector{Int64}, enus::AbstractVector{ENU}, refLLA::LLA; node_range::Number=100.0)\n\nCreate a spatial index for nodes having enus ENU coordinates using refLLA as the reference for ENU coordinates with the given node_range in meters.\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.findnode","page":"Reference","title":"OSMToolset.findnode","text":"findnode(sindex::NodeSpatIndex, point::Union{LLA, ENU})\n\nFind the node in the sindex spatial index closest to the given point coordinates.\n\nReturns 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.\n\n\n\n\n\n","category":"function"},{"location":"reference/#Tiling-OSM-file","page":"Reference","title":"Tiling OSM file","text":"","category":"section"},{"location":"reference/","page":"Reference","title":"Reference","text":"calc_tiling(::AbstractString, ::Float64, ::Float64)\ncalc_tiling(::OSMToolset.Bounds, ::Float64, ::Float64)\ntile_osm_file(::AbstractString, ::Bounds; ::Integer, ::Integer, ::AbstractString)\nBounds\ngetbounds(::AbstractString)","category":"page"},{"location":"reference/#OSMToolset.calc_tiling-Tuple{AbstractString, Float64, Float64}","page":"Reference","title":"OSMToolset.calc_tiling","text":"calc_tiling(filename::AbstractString, latTileSize::Float64, lonTileSize::Float64)\n\nCalculates recommended bounds, number of rows and columns for a given filename and size of tile latTileSize x lonTileSize.\n\n\n\n\n\n","category":"method"},{"location":"reference/#OSMToolset.calc_tiling-Tuple{Bounds, Float64, Float64}","page":"Reference","title":"OSMToolset.calc_tiling","text":"calc_tiling(bounds::Bounds, latTileSize::Float64, lonTileSize::Float64)\n\nCalculates recommended bounds, number of rows and columns for a given bounds and size of tile latTileSize x lonTileSize.\n\n\n\n\n\n","category":"method"},{"location":"reference/#OSMToolset.tile_osm_file-Tuple{AbstractString, Bounds}","page":"Reference","title":"OSMToolset.tile_osm_file","text":"tile_osm_file(filename::AbstractString, [bounds::Bounds]; nrow::Integer, ncol::Integer, [out_dir::AbstractString]\n\nProvide 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.\n\nReturns a Matrix{String} of size nrow x ncol containing the names of the files created.\n\n\n\n\n\n","category":"method"},{"location":"reference/#OSMToolset.Bounds","page":"Reference","title":"OSMToolset.Bounds","text":"A range of geographic coordinates for a map\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.getbounds-Tuple{AbstractString}","page":"Reference","title":"OSMToolset.getbounds","text":"getbounds(filename::AbstractString)::Bounds\n\nReturns Bounds that can be found in the first 10 lines of the OSM file named 'filename'\n\n\n\n\n\n","category":"method"},{"location":"reference/","page":"Reference","title":"Reference","text":"Helper functions","category":"page"},{"location":"reference/","page":"Reference","title":"Reference","text":"sample_osm_file\nFloatLon\nOSMToolset.Node","category":"page"},{"location":"reference/#OSMToolset.sample_osm_file","page":"Reference","title":"OSMToolset.sample_osm_file","text":"Provides location of sample OSM file for tests\n\n\n\n\n\n","category":"function"},{"location":"reference/#OSMToolset.FloatLon","page":"Reference","title":"OSMToolset.FloatLon","text":"This is an AbstractFloat type representing geographic longitude as the values may wrap around\n\n\n\n\n\n","category":"type"},{"location":"reference/#OSMToolset.Node","page":"Reference","title":"OSMToolset.Node","text":"Node\n\nA node is a point in the map. It has an id, a latitude and a longitude.\nAll nodes need to be stored in memory in this format.\n\n\n\n\n\n","category":"type"},{"location":"","page":"Home","title":"Home","text":"CurrentModule = OSMToolset","category":"page"},{"location":"#OSMToolset.jl","page":"Home","title":"OSMToolset.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Documentation for OSMToolset.jl","category":"page"},{"location":"","page":"Home","title":"Home","text":"For details please go to the Reference section.","category":"page"},{"location":"","page":"Home","title":"Home","text":"There is also a Visualization example.","category":"page"},{"location":"#Aknowledgments","page":"Home","title":"Aknowledgments","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"This research was funded by National Science Centre, Poland grant number 2021/41/B/HS4/03349. ","category":"page"}] } diff --git a/dev/visualize/index.html b/dev/visualize/index.html index 43c8879..f066c81 100644 --- a/dev/visualize/index.html +++ b/dev/visualize/index.html @@ -1,5 +1,5 @@ -Visualization · OSMToolset
GitHub

Visualization

How to visualize the data

The library can be integrated with various vizualisation frameworks. Below we show two example codes that can be a base for further exploration. The first example uses folium via PyCall while the second example uses Plots.jl combined with OpenStreetMapXPlot.jl.

Point of interest with Python folium via PyCall

Below is a sample piece of code that can be used to generate a visualization of POIs on a map.

using PyCall
+Visualization · OSMToolset
GitHub
Visualization
How to visualize the data
The library can be integrated with various vizualisation frameworks. Below we show two example codes that can be a base for further exploration. The first example uses folium  via PyCall while the second example uses Plots.jl combined with OpenStreetMapXPlot.jl.
Point of interest with Python folium via PyCall
Below is a sample piece of code that can be used to generate a visualization of POIs on a map.
using PyCall
 using Colors
 using OSMToolset
 
@@ -29,7 +29,7 @@
 m.fit_bounds(bounds)
 flm.Rectangle(bounds, color="blue",weight=2).add_to(m)
 
-m
The obtained result should be similar to the picture below.
POI Visualization
Buidling walkability index and vizualisation with OpenStreetMapX
using Pkg
+m
The obtained result should be similar to the picture below.
POI Visualization
Buidling walkability index and vizualisation with OpenStreetMapXPlot
In this example we download a map from the Overpass API. Next,
using Pkg
 using OSMToolset
 using DataFrames
 using Plots
@@ -39,7 +39,7 @@
 f = download("https://overpass-api.de/api/map?bbox=-71.0912,42.3550,-71.0486,42.3751")
 mv(f, "Boston.osm")
 
-""" Prepares data for plotting for a given map data ams set of POIs """
+""" Prepares data for plotting for a given map data and a set of POIs """
 function getplotdata(md, dfpoi)
 
     # All ENU coordinates should have the same reference point
@@ -47,19 +47,19 @@
 
     enus = ENU.(LLA.(dfpoi.lat, dfpoi.lon), Ref(refLLA))
     x = getX.(enus)
-    minx, maxx = minimum(x), maximum(x)
+    xmin, xmax = minimum(x), maximum(x)
     y = getY.(enus)
-    miny, maxy = minimum(y), maximum(y)
+    ymin, ymax = minimum(y), maximum(y)
 
 
     # index for efficient spatial queries for nodes
     ixnodes = NodeSpatIndex(md, refLLA; node_range=150.0)
 
     # index for efficient spatial queries for poi availability
-    # pois further than 350m  are not considered
+    # pois requiring a walk beyond 350m are not considered
     ixpoi = AttractivenessSpatIndex{NoneMetaPOI}(dfpoi, refLLA; get_range=a->350, get_group=a->:poi);
 
-    """ Calcylated a distance between a given coordinate and a POI """
+    """ Calculates the distance between a given coordinate and a POI location"""
     function mydistance(enu1, enu2)
         OpenStreetMapX.distance(enu1, enu2) > 700 && return Inf
         dist1, node1 = findnode(ixnodes, LLA(enu1, refLLA))
@@ -70,10 +70,10 @@
         dist1 + OpenStreetMapX.shortest_route(md, node1, node2)[2] + dist2
     end
 
-
     cellsize = 50  # size of a box in meters
     attdf = DataFrame()
 
+    # In order to speed-up the computations we parallelize this loop (run Julia with the -t paramater)
     lock = Threads.ReentrantLock()
     Threads.@threads for i in 0:round(Int, (xmax - xmin) / cellsize)
         for j in 0:round(Int, (ymax - ymin) / cellsize)
@@ -97,4 +97,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