Populate Predefined Edit Areas Drop Down in Zorro Tool - Hazard Services

Purpose:

Tasks:

AT-A-GLANCE:

• What? Include name/descriptor pairs of edit areas in the dictionary within an override of DescriptorDictionary,py
• Ordering: Using an OrderedDict (instead of standard Python dictionary) for your override gives control over the listing order of your edit areas ​​​​​​​​

STEP 1 (of 3) Preview current Zorro Tool before changing

1. Launch Hazard Services in GFE
2. Click the "Tools" icon on the Hazard Services Toolbar, and select "Zorro Tool"
   1. If you don't see it, you may need to switch your console settings to Winter Weather.  Click the "Setup" icon, then "Load Settings", and double-click on "Winter Weather"
3. In the "Zorro Tool" dialogue window, attempt to click on the drop-down under "Use Predefined Edit Area" and review its contents or lack thereof
   1. Out of the box, this drop-down will be empty and cannot even be clicked since nothing has been added yet

STEP 2 (of 3) Validate your desired edit areas

1.  Switch to the Localization Perspective by clicking on the "Open Perspective" icon at the top-right of your CAVE window, and choosing "Localization"
2. Navigate to the Edit Areas sub-directory under the GFE folder
3. Open the various edit areas that you may wish to add to the DescriptorDictionary. If they contain stings of LAT/LON pairs, then you can add them as-is. If they are a query, proceed to step 4.
4. If you have edit areas that are queries, open the GFE perspective and click on the ? for the Query tool. 
5. Load the edit area in question and then click Convert To Location
6. Save the edit area (it will save to User)
7. Repeat for any other query-based edit area you wish to include in the DescriptorDictionary
8. Return to the Localization Perspective, and Move your saved edit area(s) from USER to SITE

STEP 3 (of 3) Override, then test, the DescriptorDictionary

1. Switch to the Localization Perspective by clicking on the "Open Perspective" icon at the top-right of your CAVE window, and choosing "Localization"
2. In the Localization Perspective, navigate to the Utilities sub-directory under the Hazard Services folder
3. Double click on DescriptorDictionary.py to show the available versions
4. COPY to create a user override version if none exists (user override is best practice for testing changes):
   1. If there is only a BASE version: right click on BASE and select Copy To​​​​​​​, then select User
   2. If there is another version (e.g. SITE) you wish to use: right click on that file and select Copy To, then select User​​​​​​​ (this lets you work on an updated SITE version to replace the original when you're finished)
5. Double click on the USER version of DescriptorDictionary.py to open it for editing
   1. At this point notice the simple "DescriptorDictionary = { }" contents of this file.  We'll populate this with edit areas next.
6. Decide on one or more edit areas you'll use to populate this file. (See step 6.3 for a note on where this list may already exit)
   1. To choose valid edit areas, refer to the "GFE" > "Edit Areas" directory
   2. Pick one or more file-names (without the .xml suffix) for edit areas (Example: BOU_Above_5000.xml defines an edit area with the name "BOU_Above_5000")
   3. You may already have a list in your GFE files​​​​​​​: Some sites maintain a list of elevation-based edit areas in a GFE file, which could be used to populate the DescriptorDictionary. For example, localElevAreas often found in MakeHazardConfig.py
7. Switch back to the USER override of DescriptorDictionary.py you were working on
8. Update the syntax to OrderedDict ​​​​​​​as follows (if your DescriptorDictionary is already assigned as an OrderedDict, you may skip this step)
   1. Insert the below import statement before​​​​​​​ the DescriptorDictionary variable:

      from collections import OrderedDict​​​​​
      

   2. Replace the { } brackets used to assign a traditional dictionary with the syntax for and Ordered Dictionary on your DescriptorDictionary lines as follows (changes in bold):

      DescriptorDictionary = OrderedDict([ # START the ordered dictionary
      ​​​​​​​     # entries to dict would go here...
          ​​​​​​​]) # END the ordered dictionary
      

   3. Why? An ordered dictionary is a special tool for mimicking dictionary key-value pairs while maintaining the order in which values are entered, as opposed to traditional dictionaries which do not honor the order of your entries and can appear randomly shuffled when referenced, which is undesirable for scenarios like the drop-down menu that we're constructing here. Later versions of Hazard Services will use an OrderedDict as baseline for this file.
9. Populate the DescriptorDictionary with your edit area(s) as follows:
   1. On its own line within the OrderedDict ([ ]) brackets, start a tuple ( , ) entry like follows (changes in bold):

      ​​​​​​​DescriptorDictionary = OrderedDict([
          ( , ) # empty tuple value
          ])

   2. In your new tuple entry, before the comma write the exact edit area name in quotes
   3. On the same line, after the comma write a descriptor for your edit area in quotes (when used, this pre-populates location information in the segment headline and what bullet).
   4. Conclude your line line with a comma​​​​​​​ after the closing parentheses (which is necessary for additional entries, and is good practice to include now so you don't forget later). An example of your new, one-line dictionary is shown below  (changes in bold):

      ​​​​​​​DescriptorDictionary = OrderedDict([
          ('BOU_Above_1000','for elevations above 1000 feet'​​​​​), # sample OrderedDict entry
          ])

      Note the difference in notation between tuples in the OrderedDict, which separate key-value pairs by commas and group them in parentheses, versus traditional Python dictionaries which separate key-value pairs with colons and don't use a grouping symbol.
   5. ​​​​​​​Populate with any additional entries. A complete example override including the import statement and multiple, comma-separated entries is shown below:

      from collections import OrderedDict
      ​​​​​​​DescriptorDictionary = OrderedDict([
          ('BOU_Above_1000','for elevations above 1000 feet'),
          ('BOU_Above_2000','for elevations above 2000 feet'),
          ('BOU_Above_3000','for elevations above 3000 feet'),
          ('BOU_Above_4000','for elevations above 4000 feet'),
          ('BOU_Above_5000','for elevations above 5000 feet'),
          ('BOU_Above_6000','for elevations above 6000 feet'),
          ])
      

10. When finished, save the file by hitting Ctrl+S, or selecting Save from the File menu
    1. If a "File Version Conflict" is encountered, click OK to accept merge
    2. In the two-panel "Merge" tab that opens, make no changes, once again save the file by hitting Ctrl+s, then close the "Merge" tab
    3. When a "File Changed" message appears,  click Yes.
    4. This behavior will only be encountered each time a new override file that did not exist before is created and saved
11. Switch back to GFE (or whichever localization you were previously using) to once again view Hazard Services
12. Dismiss any open dialogues, then click the "Tools" icon on the Hazard Services Toolbar, and select "Zorro Tool"​​​​​​​
    1. Once again, to access this tool be sure your console settings are showing "Winter Weather"
13. In the "Zorro Tool" dialogue window, ​​​​​​​click on the drop-down under "Use Predefined Edit Area" and review its contents
    1. You should see the one or more entries you added to the DescriptorDictionary.py file. 
    2. Use these predefined areas with a selected hazard to clip the geometry to a particular location descriptor

14. Task Complete!