1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
//! # street_index //! //! [![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) //! [![Build Status Linux / macOS](https://travis-ci.org/fschutt/street_index.svg?branch=master)](https://travis-ci.org/fschutt/street_index) //! [![Build status Windows](https://ci.appveyor.com/api/projects/status/0579ea95rbpliyhi?svg=true)](https://ci.appveyor.com/project/fschutt/street-index) //! [![Rust Compiler Version](https://img.shields.io/badge/rustc-1.26%20stable-blue.svg)]() //! //! This library contains utility functions for generating a street index. //! How it works is fairly simple: You give it a grid (right now limited //! to a rectangular grid) on a page, and add `StreetNameRect`s. Each //! `StreetNameRect` contains the String for the street / road name as well //! as the extents of the laid out String on the map. //! //! The `Grid` takes care of assigning a grid position to your street name //! such as `"Canterbury Road => A2"`. Since usually maps have the problem //! of having duplicated road names (which is not what you'd want in a street //! index), you can create a `DeduplicatedRoadNames::from_streets`, which will //! deduplicate all road names. //! //! The problem generally arises when street names are ambigouus. For example, //! a street that appears in two locations on the map (such as a city having //! the same street name as a neighbouring city). Because of this, street name //! processing can't be fully automated, since there are always weird edge cases //! to worry about. However, 90% of roads aren't like that. //! //! Because of this limitation `DeduplicatedRoadNames::process()` gives you //! two types of roads back: `ProcessedRoadName` is for roads that span only //! 1 or 2 grid cells (i.e. `"Canterbury Road" => A9`, `"Canterbury Road" => A9-A10`). //! In these cases (which cover 90% of street index names), the mapping is not //! ambigouus. //! //! `UnprocessedRoadName` is for anything else (e.g. `"Canterbury Road" => [A9, A10, E1, E2]`. //! Usually these roads need to be manually reviewed - it could likely be that //! there are two roads `"Canterbury Road" => A9-10;E1-E2`, but it could also //! be that the road is just one road and part of it is just clipped off the map, //! in which case you'd write `"Canterbury Road" => A9-E2`. //! //! For cartographic purposes, usually you want the output in CSV format, so //! that your graphic designer can paste the street index into InDesign / //! Illustrator for the final map layout. Both `UnprocessedRoads` and //! `ProcessedRoads` have a simple `.to_csv` function for easy export. //! //! ## Example //! //! ```rust //! extern crate street_index; //! //! use street_index::prelude::*; //! //! fn main() { //! // Create a grid, with the page extensions being 200 x 200 millimeter //! // Each cell is 20x20 millimeter large (usually 50x50 is recommended, though) //! let mut grid = Grid::new( //! Bbox { //! width: Millimeter(200.0), //! height: Millimeter(200.0) //! }, //! GridConfig { //! cell_width: Millimeter(20.0), //! cell_height: Millimeter(20.0), //! }); //! //! // You will have to calculate the street name boundaries yourself, i.e. //! // using FreeType or RustType. Often times this will come as a side-effect //! // of your map rendering / layouting program. //! // //! // The position is relative to the top left of the grid. //! grid.insert_street(StreetNameRect { //! street_name: String::from("Canterbury Road"), //! x_from_left: Millimeter(30.0), //! width: Millimeter(50.0), //! y_from_top: Millimeter(30.0), //! height: Millimeter(8.0), //! }); //! //! // We deduplicate the roads, i.e.: //! // //! // ``` //! // "Canterbury Road" => A3 //! // "Canterbury Road" => A4 //! // ``` //! // //! // becomes: //! // //! // ``` //! // "Canterbury Road" => [A3, A4] //! // ``` //! let deduplicated = DeduplicatedRoads::from_streets(&grid.street_names()); //! //! // As described above, we get both processed and unprocessed //! // road names back //! let (processed, unprocessed) = deduplicated.process(); //! //! // In this case, "Canterbury Road" spans from B1-B2, so we get a //! // `ProcessedRoad` back, delimited by a TAB character. //! // //! // You can then write this to a CSV file if you want. //! println!("processed:\r\n{}", processed.to_csv("\t")); //! println!("unprocessed:\r\n{}", unprocessed.to_csv("\t")); //! } //! ``` //! //! ## License //! //! This library is licensed under the MIT license. /// Module for configuring the grid and assigning cell positions to road names pub mod gridconfig; /// Module for deduplicating road names and exporting / processing them to CSV pub mod roads2csv; /// Quick re-exports for wildcard imports pub mod prelude { pub use roads2csv::{ InputStreetValue, DeduplicatedRoads, ProcessedRoad, ProcessedRoadNames, UnprocessedRoad, UnprocessedRoadNames, StreetName, GridPosition, FinalizedGridPositon, }; pub use gridconfig::{ Grid, GridConfig, Bbox, Millimeter, StreetNameRect, }; }