Skip to content

v0.2.53..v0.2.54 changeset README.md

Garret Voltz edited this page Mar 31, 2020 · 1 revision
diff --git a/README.md b/README.md
index d062f8b..70ec593 100644
--- a/README.md
+++ b/README.md
@@ -11,9 +11,9 @@ _Conflation_:
 
 1. Fancy word for merge
 
-[Hootenanny](https://github.com/ngageoint/hootenanny/blob/master/docs/user/Introduction.asciidoc) is an open source conflation tool developed with machine learning techniques to facilitate automated and semi-automated conflation of critical Foundation GEOINT features in the topographic domain. **In short, it merges multiple maps into a single seamless map.**
+[Hootenanny](https://github.com/ngageoint/hootenanny/blob/master/docs/user/Introduction.asciidoc) is an open source map data conflation tool developed with machine learning techniques to facilitate automated and semi-automated conflation of critical Foundation GEOINT features in the topographic domain. **In short, it merges multiple maps into a single seamless map.**
 
-Hootenanny conflation occurs at the dataset level, where the user’s workflow determines the best reference dataset, source content, geometry, and attributes to transfer to the output map.  Hootenanny's internal processing leverages the key value pair structure of OpenStreetMap (OSM) for improved utility and applicability to broader user groups.  Normalized attributes can be used to aid in feature matching, and OSM’s free tagging system allows the map to include an unlimited number of attributes describing each feature.
+Hootenanny conflation occurs at the dataset level, where the user’s workflow determines the best reference dataset, source content, geometry, and attributes to transfer to the output map.  Hootenanny's internal processing leverages the key/value pair structure of OpenStreetMap (OSM) for improved utility and applicability to broader user groups.  Normalized attributes can be used to aid in feature matching, and OSM’s free tagging system allows the map to include an unlimited number of attributes describing each feature.
 
 # Goals
 * Automatically combine geospatial features for decision making
@@ -22,6 +22,8 @@ Hootenanny conflation occurs at the dataset level, where the user’s workflow d
 * Create up-to-date routable transportation networks from multiple sources
 
 # Conflatable Feature Types
+
+Hootenanny has conflation algorithms available for the following data types:
 * Areas
 * Buildings
 * Points of Interest (POIs)
@@ -30,58 +32,65 @@ Hootenanny conflation occurs at the dataset level, where the user’s workflow d
 * Rivers
 * Roads
 
-Additional feature types may have custom conflation routines created for them via Javascript by using Hootenanny's 
-[Generic Conflation capability](https://github.com/ngageoint/hootenanny/blob/master/docs/developer/HootenannyConflatingANewFeatureTypeWithGenericConflation.asciidoc). Any feature that does not fit into the list above will be conflated with [Generic Geometry Conflation](https://github.com/ngageoint/hootenanny/blob/master/docs/user/GenericGeometryConflation.asciidoc).
+Any feature that does not fit into the list above will be conflated with [Generic Geometry Conflation](https://github.com/ngageoint/hootenanny/blob/master/docs/user/GenericGeometryConflation.asciidoc), which uses a simpler approach than the more type specific conflation algorithms. 
+
+You can create your own custom conflation routines for additional feature types via [Javascript](https://github.com/ngageoint/hootenanny/blob/master/docs/JavascriptOverview.asciidoc) or [C++](https://github.com/ngageoint/hootenanny/blob/master/hoot-core/src/main/cpp/hoot/core/conflate/matching/MatchCreator.h). 
 
 # [Conflation](https://github.com/ngageoint/hootenanny/blob/master/docs/user/Introduction.asciidoc) Workflows
-* **[Reference Conflation](https://github.com/ngageoint/hootenanny/blob/master/docs/user/OldDocs.asciidoc)** (default) - _Keep the best of both_ - Conflate the best geometry and tag parts of map B into map A, favoring map A's data. Use this type of conflation when you want conflated output based on the best state of both input datasets.
+
+A conflation workflow defines the manner in which two maps are merged together. Hootenanny has the following workflows:
+* **[Reference Conflation](https://github.com/ngageoint/hootenanny/blob/master/docs/user/OldDocs.asciidoc)** **(default)** - _Keep the best of both_ - Conflate the best geometry and tag parts of map B into map A, favoring map A's data. Use this type of conflation when you want conflated output based on the best state of both input datasets.
 * **[Horizontal Conflation](https://github.com/ngageoint/hootenanny/blob/master/docs/commands/cookie-cut.asciidoc)** (aka Cookie Cutter Conflation) - _Replace a section_ - Either 1) Define a region in map A and replace data in that region with data in the same region from map B OR 2) Define a region in map A to preserve and replace data outside of it with data outside of the region from map B. Use this type of conflation if you have a specific region of your dataset that you would like to replace with data from another dataset or you would like to surround your dataset
 with new data.
-* **[Differential Conflation](https://github.com/ngageoint/hootenanny/blob/master/docs/algorithms/DifferentialConflation.asciidoc)** - _Add new features_ - Conflate map A with B where the only data added to the output from B is in areas that don't overlap with A. Use this type of conflation when you want to fill in holes in your dataset with data from another source without modifying any data in the first dataset.
+* **[Differential Conflation](https://github.com/ngageoint/hootenanny/blob/master/docs/algorithms/DifferentialConflation.asciidoc)** - _Add new features_ - Conflate map A with B where the only data added to the output from B is in areas that don't overlap with A. Use this type of conflation when you want to fill in holes in your dataset with data from another source without modifying any of the data in the first dataset.
 * **[Differential Conflation With Tags](https://github.com/ngageoint/hootenanny/blob/master/docs/algorithms/DifferentialConflation.asciidoc)** - _Add new features and new tags to existing features_ - This workflow is the same as Differential Conflation with the added step of transferring tags to existing features in map A from features in map B. Conflate map A with B where only tags are transferred from B to matching features in A and entire features are added from B to A in areas where B does not overlap with A.
 * **[Attribute Conflation](https://github.com/ngageoint/hootenanny/blob/master/docs/algorithms/AttributeConflation.asciidoc)** - _Transfer attributes over to geometries_ - Conflate map A with B where only tags are transferred from B to matching features in A and no changes are made to A's geometries. Use this type of conflation when the first dataset's geometry is superior to a second dataset, but the attributes of the second dataset are superior to that of the first dataset.
 
 # [Conflation Algorithms](https://github.com/ngageoint/hootenanny/blob/master/docs/algorithms/ConflationAlgsOverview.md)
 
 # Attribute Translation
-Hootenanny leverages the OSM key value pair tag concept to support translation between various data schemas and supports automated schema conversion between: 
+Hootenanny leverages the OSM key value pair tag concept to support translation between various data schemas and supports automated schema conversion between the following schemas: 
 * Topographic Data Store (TDS) 
 * Multi-National Geospatial Co-Production Program (MGCP)
 * Geonames
 * OSM 
 * [others](https://github.com/ngageoint/hootenanny/tree/master/translations)
 
-Users can define their own [custom translations](https://github.com/ngageoint/hootenanny/blob/master/docs/user/Hootenanny-id.asciidoc#translations) via Javascript or Python.
+Users can define their own [custom schema translations](https://github.com/ngageoint/hootenanny/blob/master/docs/user/Hootenanny-id.asciidoc#translations) via Javascript or Python.
 
 # Feature Validation and Cleaning
 
-Hootenanny has a variety of map cleaning capabilities to automatically correct erroneous data. In addition to the built-in cleaning operations,
-Hootenanny is integrated with the feature cleaning capabilities in [JOSM](https://josm.openstreetmap.de/). For situations where you want feature
-validation only and no automatic cleaning, JOSM validation may be used alone. There is more information on Hootenanny validation and 
-cleaning [here](https://github.com/ngageoint/hootenanny/blob/master/docs/user/FeatureValidationAndCleaning.asciidoc).
+Hootenanny has a variety of map cleaning capabilities to automatically correct erroneous data. In addition to its own built-in cleaning operations, Hootenanny is integrated with the feature cleaning capabilities of [JOSM](https://josm.openstreetmap.de/). 
+
+For situations in which you want feature
+validation only and no automatic cleaning, JOSM validation may be used by itself. More [information](https://github.com/ngageoint/hootenanny/blob/master/docs/user/FeatureValidationAndCleaning.asciidoc) on Hootenanny validation and cleaning.
+
+**NOTE:** As of 3/19/20 this capability is only available in the Vagrant version of Hootenanny. It will be added to the RPM version of Hootenanny at a later date.
 
 # Feature Filtering
 
-Hootenanny has the capability to let you selectively pick the features that are conflated from your data to save you from some pre-conflation data wrangling. Some examples:
+Hootenanny has the capability to let you selectively pick the features that are conflated from your data to save you from some pre-conflation data wrangling. 
+
+Some examples:
 * [Conflate only buildings](https://github.com/ngageoint/hootenanny/blob/master/docs/user/CommandLineExamples.asciidoc#conflate-only-buildings)
 * [Conflate only restaurant buildings](https://github.com/ngageoint/hootenanny/master/blob/docs/user/CommandLineExamples.asciidoc#conflate-only-restaurant-buildings)
 * [Conflate only restaurant buildings with "Subway" in the name](https://github.com/ngageoint/hootenanny/blob/master/docs/user/CommandLineExamples.asciidoc#conflate-only-restaurant-buildings-with-subway-in-the-name)
 
-Hootenanny has many additional [available filters](https://github.com/ngageoint/hootenanny/blob/master/docs/user/CommandLineExamples.asciidoc#list-all-entities-that-can-operate-on-data) that can also be specified to perform feature filtering during conflation.
+Hootenanny has several [available filters](https://github.com/ngageoint/hootenanny/blob/master/docs/user/CommandLineExamples.asciidoc#list-all-entities-that-can-operate-on-data) that may be used to perform feature filtering during conflation.
 
 # When To Use
-No automated map conflation technology is perfect. If you are conflating a relatively small number of features, you may be best served to conflate them manually yourself, given you are looking for perfectly conflated output and want to avoid any potential time spent configuring Hootenanny options to get the best conflated output. 
+No automated map conflation technology is perfect. If you are conflating a relatively small number of features, you may be best served to conflate them manually yourself, given you are looking for perfectly conflated output and want to avoid any potential time spent configuring software options to get the best conflated output. 
 
 For larger datasets, Hootenanny can be used standalone or as an inital step in conjunction with a crowd sourced [campaign](https://tasks.hotosm.org/) to conflate new data into your dataset. You will find that the conflation automation provided by Hootenanny saves effort overall, and that most inaccuracies in the conflated output are a small subset of the input data which end up being flagged for human review so they may later be manually corrected.
 
 # Scalability
-Hootenanny currently does not strive to conflate data at the global level. An earlier implementation of Hootenanny supported a map-reduce 
+Hootenanny currently does not strive to conflate data at a very dense global level. An earlier implementation of Hootenanny supported a map-reduce 
 architecture that was capable of global conflation for some data types but was shelved due to general lack of interest and the maintenance 
-costs to support the seldomly used capability (so some of the conflation algorithms are actually capable of supporting distributed 
-computing...with some limitations). 
+costs to support the seldom used capability (so some of the conflation algorithms are actually capable of supporting distributed 
+computing, if you want to go that route...with some limitations). 
 
 Hootenanny generally can scale well running on a single machine from the larger city level up to the smaller country level, depending on the 
-density of the data being conflated and the RAM available on the machine. Beyond that, new algorithms may need to be developed to handle very large quantities of map data.
+density of the data being conflated and the RAM available on the machine. Beyond that, new conflation algorithms will need to be developed to handle very large quantities of map data.
 
 # Configuration
 
@@ -176,13 +185,13 @@ In addition to running conflation jobs with map data, Hootenanny also provides f
 * [FAQ](https://github.com/ngageoint/hootenanny/wiki/Frequently-Asked-Questions)
 
 Don't hesitate to ask for help if features aren't conflating how you expect them to or if you're experiencing difficulty while installing the 
-software. If you have any support questions, please create an issue in this repository.
+software. We officially support installing RPMS to CentOS and launching CentOS VM's...anything else we'll do our best to help you out, but there are no guarantees. If you have any support questions, please create an issue in this repository.
 
 As there are lot of different conflation scenarios out in the wild, there is no one-size fits all conflation workflow or algorithm.  Hootenanny 
 attempts to capture most conflation scenarios with the default configuration options, but sometimes you will need to modify configuration 
 options specific to the data you are conflating in order to get the best results.
 
-Additionally, the availability of new software features to the user interface may lag their initial availability from the CLI by multiple 
+Also, the availability of new software features to the user interface may lag their initial availability from the CLI by multiple 
 development cycles. If you find a conflation feature you wish to use that is mentioned in the CLI documentation but is not present within the UI, let us know.
 
 # Development
Clone this wiki locally