2,037
edits
Changes
manual of place completion tool
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is usefull.
*Construction of a uniform title/description field, from the data in the place object
== Manual ==
== Design Specification ==
See [[Place completion tool specification]]
== Manual ==
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.
=== Download resources ===
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download datafiles of the countries you are interested in. Right now you have three options:
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp].
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need!
<small>'''Note''': The geonames data of popular places is in English, so eg municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small>
'''DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP'''
=== Starting the tool ===
The placecheck tool is in the '''tools menu''', option '''tools''', under '''Interactive place completion'''
=== The dialog explained ===
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]
The Dialog consists of 4 parts:
====Part 1: selection of places====
First you need to choose with which places you want to work. You can use several methods to define your places:
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.
====Part 2. Completion of Places ====
#The first posibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resourses, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome.
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.
#A second option is to parse some existing data in your places.
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:
###All in degree notation: use the classical degree notation with degree, minutes and seconds.
###All in decimal notation: use the decimal system to denote lat/lon.
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.
====Part 3. Overview of the results ====
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur.
[[Image:place_completion_tool_results.png]]
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry.
If the change wil '''overwrite''' an existing entry, the subentry is '''shown in orange'''.
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''
The following actions are possible in the result screen:
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.
====Part 4. Actions ====
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button.
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).
=== Example ===
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps].
We will now show how the places in this file can be completed.
TO BE COMPLETED. I WILL DO THIS EXAMPLE AS A BUG TEST OF THE CODE, AND THEN MAKE THE CODE AVAILABLE TO ALL.
== Troubleshooting ==