diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..062cab5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +_build +_static +_templates +examples/output + +*.py[cdo] +*~ + diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..9d25ad5 --- /dev/null +++ b/Makefile @@ -0,0 +1,225 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = C:/Python27/ArcGIS10.2/Scripts/sphinx-build.exe +PAPER = +BUILDDIR = ../bal-docs/ + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/BushfireAttackLevelToolbox.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/BushfireAttackLevelToolbox.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/BushfireAttackLevelToolbox" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/BushfireAttackLevelToolbox" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/README.md b/README.md index 31112f1..24f6642 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,12 @@ First download the repository into your local computer, e.g. C:\\bal. where you * Select **BAL.tbx** and click **Open**, a new toolbox called **BAL** is added to the ArcToolbox. +Testing the installation +======================== + +The code includes a suite of unit tests that ensure elements of the code base work as expected. The code should be tested before running the toolbox. Users will need to install the Nose package to run these tests. + +The test suite can be run from the main directory. On Windows, run the run_test_all.cmd script from the main BAL directory. diff --git a/bal.py b/bal.py index b7944fd..9d70e9a 100644 --- a/bal.py +++ b/bal.py @@ -20,7 +20,7 @@ from calculate_bal import bal_cal from utilities.sa_tools import extract_by_mask, reclassify, cal_slope_aspect -__version__ = '1.0' +__version__ = '2.1' def reclass_veg(veg, dem, output_folder, remap, mask): @@ -292,17 +292,18 @@ def find_aoi(extent, dem, veg): # set the environment variable and workspace arcpy.env.overwriteOutput = True - input_folder = os.path.dirname(dem) - arcpy.env.workspace = input_folder + input_dem_folder = os.path.dirname(dem) + input_veg_folder = os.path.dirname(veg) + arcpy.env.workspace = input_dem_folder # derive the effective mask based on the input data arcpy.AddMessage('Get the area of interest from the input extent ...') - mask = 'mask.shp' + mask = pjoin(input_dem_folder, 'mask.shp') if str(extent) in ['DEFAULT', 'MAXOF', 'MINOF']: # get the extent of inputs - dem_poly = "dem_poly.shp" - veg_poly = "veg_poly.shp" + dem_poly = pjoin(input_dem_folder, "dem_poly.shp") + veg_poly = pjoin(input_veg_folder, "veg_poly.shp") get_footprint(dem, dem_poly) get_footprint(veg, veg_poly) arcpy.Intersect_analysis([dem_poly, veg_poly], mask) diff --git a/conf.py b/conf.py index 047a4c2..2b1943b 100644 --- a/conf.py +++ b/conf.py @@ -1,9 +1,10 @@ # -*- coding: utf-8 -*- # -# BAL documentation build configuration file, created by -# sphinx-quickstart on Tue Jul 14 11:29:00 2015. +# Bushfire Attack Level Toolbox documentation build configuration file, created by +# sphinx-quickstart on Wed Apr 12 11:02:21 2017. # -# This file is execfile()d with the current directory set to its containing dir. +# This file is execfile()d with the current directory set to its +# containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. @@ -11,287 +12,370 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os - - # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -#cmd_folder = os.path.realpath(os.path.abspath(os.path.split(getfile(currentframe()))[0])) +# +import os +import sys sys.path.insert(0, os.path.abspath('.')) -#sys.path.append('/usr/local/python-2.7.2/lib/python2.7') - -sys.path.insert(0, os.path.abspath('./tests')) sys.path.insert(0, os.path.abspath('./utilities')) +import sphinx_rtd_theme -#sys.path.append(os.path.join(., 'tests')) -#sys.path.append(os.path.join(., 'utilities')) - -# -- General configuration ----------------------------------------------------- +# -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'] +# +needs_sphinx = '1.4.3' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.imgmath', + 'sphinx.ext.viewcode', +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix of source filenames. +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The encoding of source files. -#source_encoding = 'utf-8-sig' +# +# source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. -project = u'BAL' -copyright = u'2015, Geoscience Australia' +project = u'Bushfire Attack Level Toolbox' +copyright = u'2017, Geoscience Australia' +author = u'Geoscience Australia' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '1.0' +version = u'2.1' # The full version, including alpha/beta/rc tags. -release = '1.0' +release = u'2.1' + +numfig = True +numfig_secnum_depth = 3 # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# +# today = '' +# # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None +# The reST default role (used for this markup: `text`) to use for all +# documents. +# +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# A string of reStructuredText that will be included at the end of +# every source file that is read. +rst_epilog = """ +.. |project_name| replace:: Bushfire Attack Level Toolbox +.. |project_abbrev| replace:: BAL +.. |GA| replace:: `Geoscience Australia`_ +.. _Geoscience Australia: http://www.ga.gov.au/ +.. |DFES| replace:: `Department of Fire and Emergency Services (WA)`_ +.. _Department of Fire and Emergency Services (WA): http://www.dfes.wa.gov.au/ +.. |github| replace:: github_ +.. _github: https://github.com/GeoscienceAustralia/BAL +.. |folder_icon| image:: /docs/images/001_arcgis_folder_icon.png + +""" + # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False -# -- Options for HTML output --------------------------------------------------- + +# -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +# +RTD_NEW_THEME = True +html_theme = "sphinx_rtd_theme" +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +# +html_theme_options = { + 'navigation_depth': 4, +} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +# html_theme_path = [] -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None +# The name for this set of Sphinx documents. +# " v documentation" by default. +# +html_title = u'Bushfire Attack Level Toolbox' # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +# +# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +# +html_logo = "docs/images/geoscience_inline.jpg" -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +# +# html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# +# html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +# +# html_domain_indices = True # If false, no index is generated. -#html_use_index = True +# +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# +# html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +# +# html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +# +# html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None -# Output file base name for HTML help builder. -htmlhelp_basename = 'BALdoc' +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} -# -- Options for LaTeX output -------------------------------------------------- +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'BushfireAttackLevelToolboxdoc' + +# -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', -# Additional stuff for the LaTeX preamble. -#'preamble': '', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). latex_documents = [ - ('index', 'BAL.tex', u'BAL Documentation', - u'Geoscience Australia', 'manual'), + (master_doc, + 'BushfireAttackLevelToolbox.tex', + u'Bushfire Attack Level Toolbox Documentation', + u'Geoscience Australia', + 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# +# latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +# +# latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +# +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# +# latex_show_urls = False # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# +# latex_appendices = [] + +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True # If false, no module index is generated. -#latex_domain_indices = True +# +# latex_domain_indices = True -# -- Options for manual page output -------------------------------------------- +# -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'bal', u'BAL Documentation', - [u'Geoscience Australia'], 1) + (master_doc, + 'bushfireattackleveltoolbox', + u'Bushfire Attack Level Toolbox Documentation', + [author], 1) ] # If true, show URL addresses after external links. -#man_show_urls = False +# +# man_show_urls = False -# -- Options for Texinfo output ------------------------------------------------ +# -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'BAL', u'BAL Documentation', - u'Geoscience Australia', 'BAL', 'One line description of project.', - 'Miscellaneous'), + (master_doc, + 'BushfireAttackLevelToolbox', + u'Bushfire Attack Level Toolbox Documentation', + author, + 'BushfireAttackLevelToolbox', + 'Spatial implementation of AS3959', + 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. -#texinfo_appendices = [] +# +# texinfo_appendices = [] # If false, no module index is generated. -#texinfo_domain_indices = True +# +# texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - - -# -- Options for Epub output --------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = u'BAL' -epub_author = u'Geoscience Australia' -epub_publisher = u'Geoscience Australia' -epub_copyright = u'2015, Geoscience Australia' - -# The language of the text. It defaults to the language option -# or en if the language is not set. -#epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -#epub_identifier = '' - -# A unique identification for the text. -#epub_uid = '' - -# A tuple containing the cover image and cover page html template filenames. -#epub_cover = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files shat should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] +# +# texinfo_show_urls = 'footnote' -# A list of files that should not be packed into the epub file. -#epub_exclude_files = [] +# If true, do not generate a @detailmenu in the "Top" node's menu. +# +# texinfo_no_detailmenu = False -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 -# Allow duplicate toc entries. -#epub_tocdup = True +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/confold.py b/confold.py new file mode 100644 index 0000000..047a4c2 --- /dev/null +++ b/confold.py @@ -0,0 +1,297 @@ +# -*- coding: utf-8 -*- +# +# BAL documentation build configuration file, created by +# sphinx-quickstart on Tue Jul 14 11:29:00 2015. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +#cmd_folder = os.path.realpath(os.path.abspath(os.path.split(getfile(currentframe()))[0])) + +sys.path.insert(0, os.path.abspath('.')) +#sys.path.append('/usr/local/python-2.7.2/lib/python2.7') + +sys.path.insert(0, os.path.abspath('./tests')) +sys.path.insert(0, os.path.abspath('./utilities')) + +#sys.path.append(os.path.join(., 'tests')) +#sys.path.append(os.path.join(., 'utilities')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'BAL' +copyright = u'2015, Geoscience Australia' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'BALdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'BAL.tex', u'BAL Documentation', + u'Geoscience Australia', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'bal', u'BAL Documentation', + [u'Geoscience Australia'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'BAL', u'BAL Documentation', + u'Geoscience Australia', 'BAL', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# -- Options for Epub output --------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'BAL' +epub_author = u'Geoscience Australia' +epub_publisher = u'Geoscience Australia' +epub_copyright = u'2015, Geoscience Australia' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +#epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True diff --git a/docs/Bal_max.jpg b/docs/Bal_max.jpg deleted file mode 100644 index 160ce72..0000000 Binary files a/docs/Bal_max.jpg and /dev/null differ diff --git a/docs/acknowledgements.rst b/docs/acknowledgements.rst new file mode 100644 index 0000000..052a0df --- /dev/null +++ b/docs/acknowledgements.rst @@ -0,0 +1,26 @@ +Acknowledgements +================ + +The initial development of the Bushfire Attack Level toolbox was +supported by the Bushfire Cooperative Research Centre (2010-2014), +under the Fire Impact and Risk Evaluation Decision Support Toolbox +(FireDST) project. Translation to an ArcGIS Toolbox was sponsored +by the Department of Fire and Emergency Services, Western Australia +(2015-2017). + +.. image:: /docs/images/001_bushfire_crc_logo.jpg + :width: 200 pt + :align: left + :target: http://www.bushfirecrc.com + +.. image:: /docs/images/001_dfes_logo.jpg + :width: 200 pt + :align: left + :target: http://www.dfes.wa.gov.au + +.. image:: /docs/images/geoscience_inline.jpg + :width: 200 pt + :align: left + :target: http://www.ga.gov.au + + diff --git a/docs/background.rst b/docs/background.rst deleted file mode 100644 index 1248531..0000000 --- a/docs/background.rst +++ /dev/null @@ -1,59 +0,0 @@ -Background -============ - -The algorithm used to calculate the BAL is based on Method 1 in the Australian Standard AS 3959 (2009)--*Construction of buildings in bushfire-prone areas*. - -Method 1 is a simplified procedure that involves five steps to determine BAL, and is subject to limitations on the circumstances in which it can be used. - -**Limitation**: This method doesn't apply to the circumstances where the effective slope under the classified vegetation is more than 20 degrees downslope. - -Procedure to determine BAL --------------------------- - -According to the Standard AS 3959 (2009), five steps are involved to calculate BAL. - -**Step 1:** Select the relevant FDI based on the locations according to Table 2.1 in the Australian Standard AS 3959 (2009). For example, from Table 2.1, the FDI for Western Australia is 80. - -**Step 2:** Reclassify the input vegetation dataset into seven vegetation types defined in Table 2.3 in the Standard AS 3959 (2009). - -* 1: Forest, -* 2: Woodland, -* 3: Shrubland, -* 4: Scrub, -* 5: Mallee/Mulga, -* 6: Rainforest, -* 7: Grassland/Tussock moorland. - -The numbers from 1 to 7 are assigned to these vegetation classes respectively for calculating BAL. - -**Step 3:** Calculate the distance of the site from the classified vegetation. According to AS 3959 (2009), the vegetation is considered when its distance from the site of interest is within 100 metres. - -**Step 4:** Determine the effective slopes (the gradient from each cell) and their aspects under the classified vegetation types. If a slope's aspect is in the same direction as the vegetation from the site, this slope is regarded as a downslope that will be further analysed. Otherwise the slope is regarded as an upslope. - -When calculating BAL, upslopes and flat lands are treated as a single category. For downslopes, the Standard breaks them down into five classes: - -* 0 < downslope <= 5 degrees -* 5 < downslope <= 10 degrees -* 10 < downslope <= 15 degrees -* 15 < downslope <= 20 degrees -* > 20 degrees (beyond consideration of Method 1) - -**Step 5:** Determine the BAL from an appropriate table defined in AS 3959 (2009) based on the input FDI. For example, for Western Australia, the FDI is 80 and thus Table 2.4.3 is adopted for deriving the BAL. - -Deriving and interpreting BAL ------------------------------ - -We consider eight cardinal directions: north, northeast, east, southeast, south, southwest, west, and northwest. - -For each cardinal direction, we consider the neighbouring cells up to 100 metres from the site. We calculate the BAL for each neighbouring cell with regards to the site based on the neighbouring cell's vegetation type, upslope or downslope degrees, and its distance to the site. - -The BAL falls into a list of (12.5, 19, 29, 40, 100), where 100 represents Fire Zone (FZ). There is one more circumstances beyond Method 1 in AS 3959 (2009). - -* Where the downslope is greater than 20 degrees and there is vegetation, a constant value of 200 is given to the BAL. - -The maximum BAL is selected among all neighbouring cells in a given cardinal direction to represent the BAL for that direction. - -The final BAL for the site of interest is determined by selecting the maximum BAL from all eight cardinal directions. - - - diff --git a/docs/disclaim.rst b/docs/disclaim.rst index 46fb392..063f28b 100644 --- a/docs/disclaim.rst +++ b/docs/disclaim.rst @@ -1,9 +1,28 @@ Disclaimer ========== -Geoscience Australia has tried to make the information in this product as accurate as possible. However, it does not guarantee that the information produced by this product is totally accurate or complete. Therefore, users should use the BAL values derived from the BAL toolbox as an indicative guide only, and should not solely rely on this information when making a decision. +Geoscience Australia has tried to make the information in this product +as accurate as possible. However, it does not guarantee that the +information produced by this product is totally accurate or +complete. Therefore, users should use the BAL values derived from the +BAL toolbox as an indicative guide only, and should not solely rely on +this information when making a decision. -This work was produced at Geoscience Australia. Neither the Australian Government, Geoscience Australia nor any of their employees, makes any warranty, express or implied, or assumes any liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately-owned rights. Reference herein to any specific commercial products, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the Australian Government or Geoscience Australia. The views and opinions of authors expressed herein do not necessarily state or reflect those of the Australian Government or Geoscience Australia, and shall not be used for advertising or product endorsement purposes. +This work was produced at Geoscience Australia. Neither the Australian +Government, Geoscience Australia nor any of their employees, makes any +warranty, express or implied, or assumes any liability or +responsibility for the accuracy, completeness, or usefulness of any +information, apparatus, product, or process disclosed, or represents +that its use would not infringe privately-owned rights. Reference +herein to any specific commercial products, process, or service by +trade name, trademark, manufacturer, or otherwise, does not +necessarily constitute or imply its endorsement, recommendation, or +favoring by the Australian Government or Geoscience Australia. The +views and opinions of authors expressed herein do not necessarily +state or reflect those of the Australian Government or Geoscience +Australia, and shall not be used for advertising or product +endorsement purposes. -This document does not convey a warranty, express or implied, of merchantability or fitness for a particular purpose. +This document does not convey a warranty, express or implied, of +merchantability or fitness for a particular purpose. diff --git a/docs/execution.rst b/docs/execution.rst deleted file mode 100644 index 00513b2..0000000 --- a/docs/execution.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. |beta| unicode:: U+003B2 .. GREEK SMALL LETTER BETA - -.. _execution: - -================ -Running the tool -================ - -To calculate the BAL, we use the **BAL calculation** tool within the **BAL** toolbox installed in ArcGIS 10.2. - -Select the **BAL calculation** tool within the **BAL** toolbox, see Figure 4.5. - -.. figure:: select_bal.jpg - :align: center - :alt: Select the tool **BAL calculation**. - :figclass: align-center - - Select the tool **BAL calculation**. - -Then the **BAL calculation** window is open, see Figure 4.6. - -.. figure:: BAL_calculation_window.jpg - :align: center - :alt: The **BAL calculation** window. - :figclass: align-center - - The **BAL calculation** window. - -Parameters within the tool -========================== - -**Input DEM raster:** - - Open the input DEM file from a specific location. The DEM is required to be in a projected coordinate system with linear unit metre. For example GDA94 / MGA zone 50 is a projected spatial reference system and is suitable for use in the western part of Western Australia. More information about GDA94 / MGA zone 50 can be found `here `_. - -**Input vegetation raster:** - - Open the input vegetation dataset from the location same as the input DEM. The vegetation dataset can be in either a geographical or a projected coordinate system. It will be reprojected to the same projection and same resolution as DEM by the BAL tool. - -**Vegetation reclassification:** - - Reclassify the input vegetation classes into those defined in the Australian Standard AS 3959 (2009). There are seven classes defined in the Standard. In this tool, we give each class a unique number, i.e.: - - * 1: Forest, - * 2: Woodland, - * 3: Shrubland, - * 4: Scrub, - * 5: Mallee/Mulga, - * 6: Rainforest, - * 7: Grassland/Tussock moorland. - - A sample reclassification map is entered for the example data. The reclassification map needs to be changed by the users according to their own input vegetation data. - -**Output path:** - - Define the output location. - -**FDI value:** - - The input Fire Danger Index (FDI) value has four choices (100, 80, 50, 40) based on the locations, which are specified in the Australian Standard AS 3959 (2009). - - * 100: Australian Capital Territory (ACT), part of New South Wales (NSW) (Greater Hunter, Greater Sydney, Illawarra/Shoalhaven, Far South Coast and Southern Ranges fire weather districts), and Victoria general (excluding alpine areas). - * 80: NSW general (excluding alpine areas, and the areas with FDI 100), South Australia (SA), and Western Australia (WA). - * 50: NSW alpine areas, Tasmania, and Victoria alpine areas. - * 40: Northern Territory (NT), and Queensland (Qld). - - Select the FDI value from a suite of values (100, 80, 50, 40). It is optional. The default value is 80 that is applicable in Western Australia. - -**Extent:** - - The extent is used to select the area of interest for which BAL will be calculated. The output data extent will be where you have consistent coverage of DEM and vegetation data within the area of interest. - -**Note:** - -* There is a limitation in raster file name length and file path length in ArcGIS. For a raster name in ESRI Grid format, the maximum number of characters is 13 and for full path name, the maximum number of character is 128. For more information, `click here `_. In addition, as tested, each folder name's length should be restricted to at most eight characters. - -* The script requires that the input DEM and vegetation dataset are in the same location. The tool will fail to run when the input DEM and vegetation datasets are not in the same folder. - - -Output -====== - -A suite of rasters are produced and stored in the output folder. They represent the BAL for the area computed in each of eight cardinal directions (E, S, W, N, NE, NW, SE and SW) and the maximum BAL of all directions. Figure 4.7 is an example output. - -.. figure:: BAL_output.jpg - :align: center - :alt: An example BAL output window. - :figclass: align-center - - An example BAL output window. - - diff --git a/docs/html/.buildinfo b/docs/html/.buildinfo deleted file mode 100644 index 10f8f5a..0000000 --- a/docs/html/.buildinfo +++ /dev/null @@ -1,4 +0,0 @@ -# Sphinx build info version 1 -# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: a6ead68e29b7d9fb322b2e7b62881ebb -tags: fbb0d17656682115ca4d033fb2f83ba1 diff --git a/docs/html/_images/BAL_calculation_window.jpg b/docs/html/_images/BAL_calculation_window.jpg deleted file mode 100644 index 5ded457..0000000 Binary files a/docs/html/_images/BAL_calculation_window.jpg and /dev/null differ diff --git a/docs/html/_images/BAL_output.jpg b/docs/html/_images/BAL_output.jpg deleted file mode 100644 index 180f054..0000000 Binary files a/docs/html/_images/BAL_output.jpg and /dev/null differ diff --git a/docs/html/_images/BAL_toolbox.jpg b/docs/html/_images/BAL_toolbox.jpg deleted file mode 100644 index 299f683..0000000 Binary files a/docs/html/_images/BAL_toolbox.jpg and /dev/null differ diff --git a/docs/html/_images/addtoolbox_dialog.jpg b/docs/html/_images/addtoolbox_dialog.jpg deleted file mode 100644 index ba43d06..0000000 Binary files a/docs/html/_images/addtoolbox_dialog.jpg and /dev/null differ diff --git a/docs/html/_images/arctoolbox.jpg b/docs/html/_images/arctoolbox.jpg deleted file mode 100644 index 27141cc..0000000 Binary files a/docs/html/_images/arctoolbox.jpg and /dev/null differ diff --git a/docs/html/_images/bal_max.jpg b/docs/html/_images/bal_max.jpg deleted file mode 100644 index 160ce72..0000000 Binary files a/docs/html/_images/bal_max.jpg and /dev/null differ diff --git a/docs/html/_images/dem_example.jpg b/docs/html/_images/dem_example.jpg deleted file mode 100644 index 118b66b..0000000 Binary files a/docs/html/_images/dem_example.jpg and /dev/null differ diff --git a/docs/html/_images/example_BAL_calculation.jpg b/docs/html/_images/example_BAL_calculation.jpg deleted file mode 100644 index 42acb40..0000000 Binary files a/docs/html/_images/example_BAL_calculation.jpg and /dev/null differ diff --git a/docs/html/_images/example_process.jpg b/docs/html/_images/example_process.jpg deleted file mode 100644 index 2cefcac..0000000 Binary files a/docs/html/_images/example_process.jpg and /dev/null differ diff --git a/docs/html/_modules/bal.html b/docs/html/_modules/bal.html deleted file mode 100644 index 7f3ea7e..0000000 --- a/docs/html/_modules/bal.html +++ /dev/null @@ -1,464 +0,0 @@ - - - - - - - - - - bal — BAL 1.0 documentation - - - - - - - - - - - - -
-

Navigation

- -
- -
-
-
-
- -

Source code for bal

-"""
-:mod:`bal` - Calculate the bushfire attack level (BAL)
-===============================================================
-
-This module is used to produce the bushfire attack level (BAL) for an area of
-interest within Australia based on input vegetation and elevation datasets
-as per Method 1 in the Australian Standard AS 3959 (2009) -- Construction of
-buildings in bushfire-prone areas.
-
-:moduleauthor: Tina Yang <tina.yang@ga.gov.au>
-
-"""
-
-import sys
-import os
-import inspect
-import math
-from os.path import join as pjoin
-import arcpy
-from calculate_bal import bal_cal
-from utilities.sa_tools import extract_by_mask, reclassify, cal_slope_aspect
-
-__version__ = '1.0'
-
-
-
[docs]def reclass_veg(veg, dem, output_folder, remap, mask):
-    """
-    Reclassify the original vegetation into the categories classified as Table
-    2.3 in AS 3959 (2009).
-
-    :param veg: `file` the input vegetation
-    :param dem: `file` the input dem used as reference projection
-    :param output_folder: `str` the output folder
-    :param remap: `srt` the vegetation reclassification
-    :param mask: `file` the mask for the effective AOI
-
-    :return: `file` the reclassified vegetation
-    """
-
-    arcpy.env.overwriteOutput = True
-
-    input_folder = os.path.dirname(veg)
-    arcpy.env.workspace = input_folder
-
-    veg_r_init = 'veg_r_init'
-    veg_r_proj = pjoin(input_folder,'veg_r_pj')
-    veg_class_r = pjoin(output_folder, 'veg_r')
-
-    arcpy.AddMessage('Remap the vegetation into classes of 1 ~ 7 ...')
-
-    # Derive reclassifed veg...
-    reclassify(veg, remap, veg_r_init)
-
-    # project as dem and change cell size same as that of dem
-    dem_c = arcpy.GetRasterProperties_management(dem, "CELLSIZEX").getOutput(0)
-
-    arcpy.ProjectRaster_management(veg_r_init, veg_r_proj, dem, "#", dem_c)
-
-    if arcpy.Exists(veg_r_init):
-        arcpy.Delete_management(veg_r_init)
-
-    # get the AOI
-    extract_by_mask(veg_r_proj, mask, veg_class_r)
-
-    g_list = arcpy.ListRasters('g_g*')
-    if len(g_list) != 0:
-        for g_file in g_list:
-            arcpy.Delete_management(g_file)
-
-    if arcpy.Exists(veg_r_proj):
-        arcpy.Delete_management(veg_r_proj)
-
-    return veg_class_r
-
-

-
[docs]def get_slope_aspect(input_dem, output_folder, mask):
-    """
-    Calculate the slope and aspect from the input DEM
-
-    :param input_dem: `file` the input DEM
-    :param output_folder: `str` the output folder
-    :param mask: `file` the mask for the effective AOI
-
-    :return: `file` the reclassified slope
-    :return: `file` the reclassified aspect
-    """
-    arcpy.env.overwriteOutput = True
-
-    input_folder = os.path.dirname(input_dem)
-    arcpy.env.workspace = input_folder
-
-    dem_slope = pjoin(input_folder, 'slope')
-    dem_aspect = pjoin(input_folder,'aspect')
-
-    # Derive slope and aspect ...
-    cal_slope_aspect(input_dem, dem_slope, dem_aspect)
-
-    aspect_rec_init = pjoin(input_folder, 'aspect_r_i')
-    slope_rec_init = pjoin(input_folder, 'slope_r_i')
-    aspect_rec = pjoin(output_folder, 'aspect_r')
-    slope_rec = pjoin(output_folder, 'slope_r')
-
-    # Derive reclassifed aspect...
-    arcpy.AddMessage('Remap the aspect into classes of 1 ~ 9 ...')
-
-    reclassify(dem_aspect, "-1 0 9;0 22.5 1;22.5 67.5 2;67.5 112.5 3;\
-               112.5 157.5 4;157.5 202.5 5;202.5 247.5 6;247.5 292.5 7;\
-               292.5 337.5 8;337.5 360 1", aspect_rec_init)
-
-    value_max = arcpy.GetRasterProperties_management(
-                dem_slope, "MAXIMUM").getOutput(0)
-
-    if float(value_max) < 20:
-        value_max = 20.0001
-
-    # remap is minimum inclusive but maxmum exclusive. using .0001 to comform
-    # to the standard minimum is exclusive and maximum is inclusive
-    remap = "0 0 1;0.0001 5 2;5.0001 10 3;10.0001 15 4;\
-            15.0001 20 5;20.0001 " + \
-            str(math.ceil(float(value_max))) + " 6"
-
-    arcpy.AddMessage('Remap the slope into classes of 1 ~ 6 ...')
-
-    # Derive reclassifed slope...
-    reclassify(dem_slope, remap, slope_rec_init)
-
-    extract_by_mask(aspect_rec_init, mask, aspect_rec)
-    extract_by_mask(slope_rec_init, mask, slope_rec)
-
-    g_list = arcpy.ListRasters('g_g*')
-    if len(g_list) != 0:
-        for g_file in g_list:
-            arcpy.Delete_management(g_file)
-    if arcpy.Exists(dem_slope):
-        arcpy.Delete_management(dem_slope)
-    if arcpy.Exists(dem_aspect):
-        arcpy.Delete_management(dem_aspect)
-    if arcpy.Exists(slope_rec_init):
-        arcpy.Delete_management(slope_rec_init)
-    if arcpy.Exists(aspect_rec_init):
-        arcpy.Delete_management(aspect_rec_init)
-
-    return slope_rec, aspect_rec
-
-

-
[docs]def find_common_area(veg_class, slope, aspect):
-    """
-    Find the common area of vegetation, slope and aspect to calculate BAL.
-
-    :param veg_class: `file` the reclassified vegetation
-    :param slope: `file` the slope derived from DEM
-    :param aspect: `file` the aspect derived from DEM
-
-    :return: `file` the vegetation in common area
-    :return: `file` the slope in common area
-    :return: `file` the aspect in common area
-    """
-
-    output_folder = os.path.dirname(veg_class)
-    arcpy.env.overwriteOutput = True
-
-    # set directory
-    work_folder = output_folder
-    os.chdir(work_folder)
-    arcpy.env.workspace = work_folder
-
-    # get the common area of veg and dem
-    # get the extent of inputs
-    slope_poly = "slope_poly.shp"
-    veg_class_poly = "veg_class_poly.shp"
-    get_footprint(slope, slope_poly)
-    get_footprint(veg_class, veg_class_poly)
-
-    mask_com = 'mask_com.shp'
-
-    arcpy.Intersect_analysis([slope_poly, veg_class_poly], mask_com)
-
-    veg_class_com = pjoin(output_folder, 'veg_c')
-    slope_com = pjoin(output_folder, 'slope_c')
-    aspect_com = pjoin(output_folder, 'aspect_c')
-
-    extract_by_mask(veg_class, mask_com, veg_class_com)
-    extract_by_mask(slope, mask_com, slope_com)
-    extract_by_mask(aspect, mask_com, aspect_com)
-
-    if arcpy.Exists(slope_poly):
-        arcpy.Delete_management(slope_poly)
-    if arcpy.Exists(veg_class_poly):
-        arcpy.Delete_management(veg_class_poly)
-    if arcpy.Exists(mask_com):
-        arcpy.Delete_management(mask_com)
-    if arcpy.Exists(veg_class):
-        arcpy.Delete_management(veg_class)
-    if arcpy.Exists(slope):
-        arcpy.Delete_management(slope)
-    if arcpy.Exists(aspect):
-        arcpy.Delete_management(aspect)
-
-    return veg_class_com, slope_com, aspect_com
-
-

-
[docs]def bal_calc(vegetation, dem, fdi, output_folder, remap, mask):
-    """
-    Calcuate BAL based on vegetation map and DEM.
-
-    :param vegetation: `file` the original vegetation
-    :param dem: `file` the input DEM
-    :param fdi: `int` the input FDI value
-    :param output_folder: `str` the output folder
-    :param remap: `srt` the vegetation reclassification
-    :param mask: `file` the mask for the effective area of interest (AOI)
-    """
-    arcpy.env.overwriteOutput = True
-
-    arcpy.AddMessage('Reclassify the vegetation map ...   ')
-    veg_class = reclass_veg(vegetation, dem, output_folder, remap, mask)
-
-    arcpy.AddMessage('Reclassify slope and aspect ...   ')
-    slope, aspect = get_slope_aspect(dem, output_folder, mask)
-
-    if arcpy.Exists(mask):
-        arcpy.Delete_management(mask)
-
-    # extract the common area between vegtation, slope and aspect
-    arcpy.AddMessage('Get common area of input data ...   ')
-    veg_class_com, slope_com, aspect_com = find_common_area(veg_class,
-                                                            slope, aspect)
-
-    arcpy.AddMessage('Calculate the BAL ...   ')
-    bal_cal(veg_class_com, slope_com, aspect_com, fdi)
-
-

-
[docs]def get_extent_mask(extent, mask):
-    """
-    Derive the mask for the customised input extent.
-
-    :param extent: `str` the input extent
-    :param mask: `file` the output mask
-    """
-
-    extent_list = str(extent).split()
-
-    # Array to hold points
-    array = arcpy.Array()
-
-    # Create the bounding box
-    array.add(arcpy.Point(float(extent_list[0]), float(extent_list[1])))
-    array.add(arcpy.Point(float(extent_list[2]), float(extent_list[1])))
-    array.add(arcpy.Point(float(extent_list[2]), float(extent_list[3])))
-    array.add(arcpy.Point(float(extent_list[0]), float(extent_list[3])))
-    array.add(arcpy.Point(float(extent_list[0]), float(extent_list[1])))
-
-    # Create the polygon object
-    polygon = arcpy.Polygon(array)
-    array.removeAll()
-    arcpy.CopyFeatures_management(polygon, mask)
-
-

-
[docs]def get_footprint(raster, footprint):
-    """
-    Find the footprint of a raster
-
-    :param raster: `file` the input raster
-    :param footprint: `file` the output footprint
-    """
-
-    # set the environment variable and workspace
-    arcpy.env.overwriteOutput = True
-    input_folder = os.path.dirname(raster)
-    arcpy.env.workspace = input_folder
-
-    raster_extent = arcpy.Describe(raster).extent
-
-    get_extent_mask(raster_extent, footprint)
-
-    # add the original spatial reference to the footprint
-    desc = arcpy.Describe(raster)
-    arcpy.DefineProjection_management(footprint, desc.spatialReference)
-
-

-
[docs]def find_aoi(extent, dem, veg):
-    """
-    Find the effective area of interest based on input vegetation map, DEM and
-    extent.
-
-    :param extent: `str` the input extent
-    :param dem: `file` the input DEM
-    :param veg: `file` the input vegetation
-
-    :return: `file` the mask for effective AOI
-    """
-
-    # set the environment variable and workspace
-    arcpy.env.overwriteOutput = True
-    input_folder = os.path.dirname(dem)
-    arcpy.env.workspace = input_folder
-
-    # derive the effective mask based on the input data
-    arcpy.AddMessage('Get the area of interest from the input extent ...')
-    mask = 'mask.shp'
-
-    if str(extent) in ['DEFAULT', 'MAXOF', 'MINOF']:
-        # get the extent of inputs
-        dem_poly = "dem_poly.shp"
-        veg_poly = "veg_poly.shp"
-        get_footprint(dem, dem_poly)
-        get_footprint(veg, veg_poly)
-        arcpy.Intersect_analysis([dem_poly, veg_poly], mask)
-
-        # delete intermediate files
-        if arcpy.Exists(dem_poly):
-            arcpy.Delete_management(dem_poly)
-        if arcpy.Exists(veg_poly):
-            arcpy.Delete_management(veg_poly)
-    else:
-        get_extent_mask(extent, mask)
-
-        # add dem's spatial reference to the mask
-        desc = arcpy.Describe(dem)
-        arcpy.DefineProjection_management(mask, desc.spatialReference)
-
-    return mask
-
-

-
[docs]def run():
-    """
-    Run the BAL calculations.
-
-    """
-    # add subfolders into path
-    cmd_folder = os.path.realpath(
-        os.path.abspath(
-            os.path.split(
-                inspect.getfile(
-                    inspect.currentframe()))[0]))
-    if cmd_folder not in sys.path:
-        sys.path.insert(0, cmd_folder)
-
-    cmd_subfolder = pjoin(cmd_folder, "utilities")
-    if cmd_subfolder not in sys.path:
-        sys.path.insert(0, cmd_subfolder)
-
-    # get input parameters from toolbox interface
-    dem = arcpy.GetParameterAsText(0)
-    veg = arcpy.GetParameterAsText(1)
-    remap = arcpy.GetParameterAsText(2)
-    output_folder = arcpy.GetParameterAsText(3)
-    fdi = arcpy.GetParameter(4)
-    extent = arcpy.GetParameter(5)
-
-    dem_sr = arcpy.Describe(dem).spatialReference
-    arcpy.AddMessage("DEM's spatial reference type is {0}".format(dem_sr.type))
-
-    if dem_sr.type == "Projected":
-        # find effective AOI based on the input parameters
-        mask = find_aoi(extent, dem, veg)
-
-        try:
-            # calculate the BAL for the effective AOI
-            bal_calc(veg, dem, fdi, output_folder, remap, mask)
-            arcpy.AddMessage("Successfully completed BAL calculation!")
-        except Exception as err:
-            # Report any exceptions back
-            arcpy.AddError(err)
-
-    else:
-        arcpy.AddError("To go ahead, the DEM needs to be projected first")
-

-if __name__ == '__main__':
-    run()
-
- -
-
-
-
-
- - -
-
-
-
-
-

Navigation

- -
-
- © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
- - \ No newline at end of file diff --git a/docs/html/_modules/calculate_bal.html b/docs/html/_modules/calculate_bal.html deleted file mode 100644 index c5e1716..0000000 --- a/docs/html/_modules/calculate_bal.html +++ /dev/null @@ -1,391 +0,0 @@ - - - - - - - - - - calculate_bal — BAL 1.0 documentation - - - - - - - - - - - - -
-

Navigation

- -
- -
-
-
-
- -

Source code for calculate_bal

-"""
-:mod:`calculate_bal` - essential part of calculating the
-bushfire attack level (BAL)
-
-===============================================================
-
-This module includes algorithms that are used to calculate BAL as per
-Method 1 in the Australian Standard AS 3959 (2009) -- Construction of
-buildings in bushfire-prone areas.
-
-:moduleauthor: Tina Yang <tina.yang@ga.gov.au>
-
-"""
-
-import arcpy
-import os
-import numpy as np
-from utilities import value_lookup, bal_database
-
-
-
[docs]def bal_cal(veg_class, slope, aspect, fdi):
-    """
-    Calculate the BAL based on the classified vegetation and the combined
-    slope and vegetation according to an appropriate table in AS 3959 (2009)
-    to determine the bushfire attack level (BAL).
-
-    :param veg_class: `file` the input classified vegetation
-    :param slope: `file` the input slope
-    :param aspect: `file` the input aspect
-    :param fdi: `int` the input FDI value
-    """
-
-    output_folder = os.path.dirname(veg_class)
-    arcpy.env.overwriteOutput = True
-
-    # set directory
-    work_folder = output_folder
-    os.chdir(work_folder)
-    arcpy.env.workspace = work_folder
-
-    # get veg raster size, format, projection, etc
-    desc = arcpy.Describe(veg_class)
-    extent = desc.extent
-    lowleft_corner = arcpy.Point(extent.XMin, extent.YMin)
-    pixel_w = desc.meanCellWidth
-    pixel_h = desc.meanCellHeight
-    sref = desc.spatialReference
-
-    # load the raster into numpy array
-    veg_data = arcpy.RasterToNumPyArray(veg_class, nodata_to_value=-99)
-    slope_data = arcpy.RasterToNumPyArray(slope, nodata_to_value=-99)
-    aspect_data = arcpy.RasterToNumPyArray(aspect, nodata_to_value=-99)
-
-    # calculate the BAL for each direction in numpy array and get maximum of
-    # 2 direction each time, until get the maximum of all directions
-    dire = ['w', 'e', 'n', 's', 'nw', 'ne', 'se', 'sw']
-
-    for one_dir in dire:
-        bal_list = []
-        outdata = convo(one_dir, veg_data, slope_data, aspect_data,
-                        pixel_w, fdi)
-
-        output_dir = 'bal_' + one_dir + '.img'
-
-        if arcpy.Exists(output_dir):
-            arcpy.Delete_management(output_dir)
-
-        arcpy.NumPyArrayToRaster(outdata, lowleft_corner, pixel_w,
-                                 pixel_h, value_to_nodata=-99).save(output_dir)
-
-        arcpy.DefineProjection_management(output_dir, sref)
-
-        if one_dir == 'w':
-            bigger = outdata
-            del outdata
-            continue
-
-        bal_list.append(bigger)
-        bal_list.append(outdata)
-        bigger = get_max_bal(bal_list)
-        del outdata
-
-    # get maximum BAL from the list
-    arcpy.NumPyArrayToRaster(bigger, lowleft_corner, pixel_w,
-                             pixel_h, value_to_nodata=-99).save('bal_max.img')
-
-    arcpy.DefineProjection_management('bal_max.img', sref)
-
-    arcpy.BuildPyramidsandStatistics_management(output_folder, "#",
-                                                "BUILD_PYRAMIDS",
-                                                "CALCULATE_STATISTICS")
-
-    # delete intermediate results
-    if arcpy.Exists(veg_class):
-        arcpy.Delete_management(veg_class)
-    if arcpy.Exists(slope):
-        arcpy.Delete_management(slope)
-    if arcpy.Exists(aspect):
-        arcpy.Delete_management(aspect)
-    del veg_data, slope_data, aspect_data
-    del bal_list, bigger
-
-

-
[docs]def get_max_bal(bal_list):
-    """
-    get the maximum bal value of all 8 directions.
-
-    :param bal_list: `list of arrays` the bal value for each of 8 directions
-
-    :return: :class:`numpy.ndarray` the maximum bal value of 8 directions
-    """
-
-    stacked_arrays = np.dstack(tuple(bal_list))
-    max_of_stack = stacked_arrays.max(2)
-
-    return max_of_stack
-
-

-
[docs]def get_slope_in_aspect(slope_data, aspect_data, rows, cols, aspect_value):
-    """
-    Get the slope data in a specific aspect.
-
-    :param slope_data: :class:`numpy.ndarray` the slope values
-    :param aspect_data: :class:`numpy.ndarray` the aspect values
-    :param rows: `int` the row number of the slope_data
-    :param cols: `int` the column number of the slope_data
-    :param aspect_value: `int` the aspect value
-
-    :return: :class:`numpy.ndarray` the slope data in an aspect
-    """
-
-    slope_in_aspect = np.zeros((rows, cols), np.float32)
-    # -1 means upslope
-    slope_in_aspect.fill(-1)
-    # if the original slope is nodata, the slope_in_aspect should be nodata
-    nodata_location = np.where(slope_data == -99)
-    slope_in_aspect[nodata_location] = slope_data[nodata_location]
-
-    same_aspect_location = np.where(aspect_data == aspect_value)
-    slope_in_aspect[same_aspect_location] = slope_data[same_aspect_location]
-
-    return slope_in_aspect
-
-

-
[docs]def convo(a_dir, veg_data, slope_data, aspect_data, pixel_width, fdi):
-    """
-    Find the maximum BAL for the point of interest in one direction by
-    assessing all neighbours' BAL values in that direction (up to 100 metres).
-
-    :param a_dir: `string` the specific direction
-    :param veg_data: :class:`numpy.ndarray` the classified vegetation values
-    :param slope_data: :class:`numpy.ndarray` the slope values
-    :param aspect_data: :class:`numpy.ndarray` the aspect values
-    :param pixel_width: `float` the pixel width of the classified vegetation
-    :param fdi: `int` the input FDI value
-
-    :return: :class:`numpy.ndarray` the output BAL values
-    """
-
-    dire_aspect = value_lookup.DIRE_ASPECT
-    aspect_value = dire_aspect[a_dir]
-
-    # dire_width is the cell span length at the specific direction
-    if a_dir in ['w', 'e', 'n', 's']:
-        dire_width = pixel_width
-    else:
-        dire_width = pixel_width * 1.414
-
-    filter_width = int(np.ceil(100.0 / dire_width))
-
-    rows = veg_data.shape[0]
-    cols = veg_data.shape[1]
-
-    slope_in_aspect = get_slope_in_aspect(slope_data, aspect_data, rows, cols,
-                                          aspect_value)
-
-    outdata = np.zeros((rows, cols), np.float32)
-
-    for i in range(rows):
-        for jj in range(cols):
-
-            # for pixels whose neighbour amount is less than defined value.
-            # e.g here for 25m resolution, it is 4 for hori and vert and 3
-            # for diagnoal direction
-            all_neighb_dir = value_lookup.ALL_NEIGHB[a_dir](i, jj, rows, cols)
-
-            if all_neighb_dir < filter_width:
-                max_neighb_dir = all_neighb_dir
-            else:
-                max_neighb_dir = filter_width
-
-            slope = np.zeros(max_neighb_dir)
-            veg = np.zeros(max_neighb_dir)
-            bal = np.zeros(max_neighb_dir)
-            dist = np.zeros(max_neighb_dir)
-
-            # if max_neighb_dir is 0, it means no neighbours at this direction
-            # so no loop is acted as follows. then the output is nodata
-            for m in range(1, max_neighb_dir + 1):
-                # get neighbour point location
-                point_row = value_lookup.POINT_R[a_dir](i, m)
-                point_col = value_lookup.POINT_C[a_dir](jj, m)
-
-                # get neighbour point distance, slope, veg data
-                dist[m - 1] = (m - 1) * dire_width + 0.5 * dire_width
-                slope[m - 1] = slope_in_aspect[point_row, point_col]
-                veg[m - 1] = veg_data[point_row, point_col]
-
-                # calcualte bal for the neighbour point
-                bal[m - 1] = bal_esti(veg[m - 1],
-                                      dist[m - 1], slope[m - 1], fdi)
-
-            # get the calculated pixel value
-            if len(bal) > 0:
-                outdata[i, jj] = max(bal)
-            else:
-                # the boundary data
-                outdata[i, jj] = -99
-
-    return outdata
-
-

-
[docs]def find_dist_class(dist, dist_limit):
-    """
-    Decide the BAL class based on the input distance and the distance
-    upper-limit for each BAL class.
-
-    :param dist: `float` the horizontal distance from POI
-    :param dist_limit: `list` the upper-limit for each BAL class
-
-    :return: `int` the distance class defined in bal_database.py
-    """
-
-    if dist < dist_limit[0]:
-        dist_class = 1
-    elif dist < dist_limit[1]:
-        dist_class = 2
-    elif dist < dist_limit[2]:
-        dist_class = 3
-    elif dist < dist_limit[3]:
-        dist_class = 4
-    else:
-        dist_class = 5
-
-    return dist_class
-
-

-
[docs]def bal_esti(veg, dist, slope, fdi):
-    """
-    Calculate the BAL based on the vegetation class, slope degree and
-    horizontal distance from the point of interest (POI).
-
-    :param veg: `float` the vegetation type
-    :param dist: `float` the horizontal distance from POI
-    :param slope: `float` the slope value
-    :param fdi: `int` the input FDI value
-
-    :return: `float` the output BAL value for this neighbour point regards to
-             the POI
-    """
-
-    # nodata area
-    if slope == -99:
-        bal = -99
-
-    # downslope > 20 degree
-    elif slope == bal_database.SLOPE[5]:
-        if veg == -99:
-            bal = -99
-        else:
-            bal = 200
-
-    # flat land (0 degree) or upslopes
-    elif slope in [-1, bal_database.SLOPE[0]]:
-        if veg == -99:
-            bal = -99
-        else:
-            d_limit = bal_database.DIST_LIMIT_UPSLOPE[fdi][veg]
-            dist_class = find_dist_class(dist, d_limit)
-            bal = bal_database.BAL_CLASS[dist_class]
-
-    # 0 < downslope <= 20 degree
-    else:
-        if veg == -99:
-            bal = -99
-        else:
-            d_limit = bal_database.DIST_LIMIT_DOWNSLOPE[fdi][(slope, veg)]
-            dist_class = find_dist_class(dist, d_limit)
-            bal = bal_database.BAL_CLASS[dist_class]
-
-    # if fdi is not 50, if it is grassland, distance is consdiered up to 50m,
-    # update bal to nodata
-    if fdi != 50 and veg == bal_database.VEG_CLASS[6]:
-        if dist >= 50:
-            bal = -99
-
-    return bal

-
- -
-
-
-
-
- - -
-
-
-
-
-

Navigation

- -
-
- © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
- - \ No newline at end of file diff --git a/docs/html/_modules/index.html b/docs/html/_modules/index.html deleted file mode 100644 index 23915ff..0000000 --- a/docs/html/_modules/index.html +++ /dev/null @@ -1,94 +0,0 @@ - - - - - - - - - - Overview: module code — BAL 1.0 documentation - - - - - - - - - - - -
-

Navigation

- -
- -
-
-
-
- -

All modules for which code is available

- - -
-
-
-
-
- - -
-
-
-
-
-

Navigation

- -
-
- © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
- - \ No newline at end of file diff --git a/docs/html/_modules/sa_tools.html b/docs/html/_modules/sa_tools.html deleted file mode 100644 index 819d68b..0000000 --- a/docs/html/_modules/sa_tools.html +++ /dev/null @@ -1,359 +0,0 @@ - - - - - - - - - - sa_tools — BAL 1.0 documentation - - - - - - - - - - - - -
-

Navigation

- -
- -
-
-
-
- -

Source code for sa_tools

-"""
-:mod:`sa_tools` - some support functions replacing spatial analyst
-
-===============================================================
-
-This module includes algorithms that are used to replace spatial analyst
-functions such as ExtractByMask, Reclassify, Slope and Aspect used within this
-package.
-
-:moduleauthor: Tina Yang <tina.yang@ga.gov.au>
-
-"""
-
-from __future__ import absolute_import
-
-import numpy as np
-from scipy import ndimage
-import numexpr
-import arcpy
-import os
-
-RADIANS_PER_DEGREE = 0.01745329251994329576923690768489
-
-
[docs]def clip_array(data, x_left, y_upper, pixelwidth, pixelheight, extent):
-
-    """
-    Return the clipped area of the input array according to an sub-extent
-    :param data: :class:`numpy.ndarray` the input array
-    :param x_left: `float` the left-most x projected coordinate
-    :param y_upper: `float` the upper-most y projected coordinate
-    :param pixelwidth: `float` the pixel width
-    :param pixelheight: `float` the pixel height
-    :param extent: `tuple` the clipping extent
-    :return: :class:`numpy.ndarray` the clipped array
-    """
-
-    x_start = int(np.around((extent[0] - x_left)/pixelwidth))
-    y_start = int(np.around((y_upper - extent[3])/pixelheight))
-
-    cols = int(np.around((extent[2] - extent[0])/pixelwidth))
-    rows = int(np.around((extent[3] - extent[1])/pixelheight))
-
-    x_end = x_start + cols
-    y_end = y_start + rows
-
-    data_clip = data[y_start:y_end, x_start:x_end]
-
-    return data_clip
-
-

-
[docs]def extract_by_mask(image_fname, extent_file, out_fname):
-    """
-    Extract a raster using a feature (shape) file
-    :param image_fname: `file` the input raster
-    :param extent_file: `file` the input extent feature file
-    :return: `file` the output raster
-    """
-
-    output_folder = os.path.dirname(image_fname)
-    arcpy.env.overwriteOutput = True
-
-    # set directory
-    work_folder = output_folder
-    os.chdir(work_folder)
-    arcpy.env.workspace = work_folder
-
-    # set nodata value
-    nodata_value = -99
-
-    # get the information of the original image
-    desc = arcpy.Describe(image_fname)
-    x_min = desc.extent.XMin
-    y_min = desc.extent.YMin
-    x_max = desc.extent.XMax
-    y_max = desc.extent.YMax
-    pixel_w = desc.meanCellWidth
-    pixel_h = desc.meanCellHeight
-    sref = desc.spatialReference
-    data = arcpy.RasterToNumPyArray(image_fname, nodata_to_value=nodata_value)
-
-    # rasterise the shapefile and then extract into numpy array
-    ext_raster = "ext_raster"
-    arcpy.FeatureToRaster_conversion(extent_file, "FID", ext_raster, pixel_w)
-    extent_data = arcpy.RasterToNumPyArray(ext_raster,
-                                           nodata_to_value=nodata_value)
-
-    # decide the effective extent to extract the raster
-    extent = arcpy.Describe(extent_file).extent
-    if extent.XMin < x_min:
-        effect_xmin = x_min
-    else:
-        effect_xmin = extent.XMin
-
-    if extent.YMin < y_min:
-        effect_ymin = y_min
-    else:
-        effect_ymin = extent.YMin
-
-    if extent.XMax > x_max:
-        effect_xmax = x_max
-    else:
-        effect_xmax = extent.XMax
-
-    if extent.YMax > y_max:
-        effect_ymax = y_max
-    else:
-        effect_ymax = extent.YMax
-
-    effect_extent = (effect_xmin, effect_ymin, effect_xmax, effect_ymax)
-
-    # get the lowleft corner for positioning the output raster
-    lowleft_corner = arcpy.Point(effect_xmin, effect_ymin)
-
-    # extract the effective extent of interest from original image data
-    data_in_extent = clip_array(data, x_min, y_max, pixel_w, pixel_h,
-                                effect_extent)
-
-    # extract the effective extent of interest from original extent data
-    extent_data_effect = clip_array(extent_data, extent.XMin, extent.YMax,
-                                    pixel_w, pixel_h, effect_extent)
-
-    # operate extent_data_effect and data_in_extent, if nodata in either,
-    # output is nodata
-    nodata_area = np.where(extent_data_effect == nodata_value)
-    data_in_extent[nodata_area] = nodata_value
-
-    # save the output array into a raster
-    arcpy.NumPyArrayToRaster(data_in_extent, lowleft_corner, pixel_w, pixel_h,
-                             value_to_nodata=nodata_value).save(out_fname)
-    arcpy.DefineProjection_management(out_fname, sref)
-
-
-    del data_in_extent
-    del extent_data_effect
-    del data
-
-    if arcpy.Exists(ext_raster):
-        arcpy.Delete_management(ext_raster)
-
-

-
[docs]def reclassify(image_fname, remap, out_fname):
-    """
-    Reclassify the raster as per the input remap
-    :param image_fname: `file` the input raster
-    :param remap: `str` the info of remap
-    :return: `file` the output raster
-    """
-
-    output_folder = os.path.dirname(image_fname)
-    arcpy.env.overwriteOutput = True
-
-    # set directory
-    work_folder = output_folder
-    os.chdir(work_folder)
-    arcpy.env.workspace = work_folder
-
-    # set nodata value
-    nodata_value = -99
-
-    # get the information of the original image
-    desc = arcpy.Describe(image_fname)
-    x_min = desc.extent.XMin
-    y_min = desc.extent.YMin
-    pixel_w = desc.meanCellWidth
-    pixel_h = desc.meanCellHeight
-    sref = desc.spatialReference
-    # get the lowleft corner for positioning the output raster
-    lowleft_corner = arcpy.Point(x_min, y_min)
-
-    data = arcpy.RasterToNumPyArray(image_fname, nodata_to_value=nodata_value)
-
-    remap_list = remap.split(";")
-
-    for a_map in remap_list:
-        values = a_map.lstrip().split(" ")
-        if len(values) == 2:
-            start_value = float(values[0])
-            end_value = float(values[0])
-            new_value = values[1]
-        else:
-            start_value = float(values[0])
-            end_value = float(values[1])
-            new_value = values[2]
-
-        # to include the orignal end value , expand the end value a bit
-        end_value += 0.0001
-
-        if new_value == 'NODATA':
-            new_value = nodata_value
-        else:
-            new_value = int(new_value)
-
-        range_loc = np.where((data >= start_value) & (data < end_value))
-        data[range_loc] = new_value
-
-    data = data.astype(int)
-    # save the output array into a raster
-    arcpy.NumPyArrayToRaster(data, lowleft_corner, pixel_w, pixel_h,
-                             value_to_nodata=nodata_value).save(out_fname)
-    arcpy.DefineProjection_management(out_fname, sref)
-
-    del data
-
-

-
[docs]def cal_slope_aspect(dem, slope_fname, aspect_fname):
-    """
-    Calculate the slope from the input dem
-    :param dem: `file` the input dem
-    :param slope_fname: `file` the output slope
-    :param aspect_fname: `file` the output aspect
-    """
-
-    output_folder = os.path.dirname(dem)
-    arcpy.env.overwriteOutput = True
-
-    # set directory
-    work_folder = output_folder
-    os.chdir(work_folder)
-    arcpy.env.workspace = work_folder
-
-    # set nodata value
-    nodata_value = -99
-
-    # get the information of the original image
-    desc = arcpy.Describe(dem)
-    x_min = desc.extent.XMin
-    y_min = desc.extent.YMin
-    pixel_w = desc.meanCellWidth
-    pixel_h = desc.meanCellHeight
-    sref = desc.spatialReference
-    # get the lowleft corner for positioning the output raster
-    lowleft_corner = arcpy.Point(x_min, y_min)
-
-    elevation_array = arcpy.RasterToNumPyArray(dem,
-                                               nodata_to_value=nodata_value)
-
-    mask = np.where(elevation_array == nodata_value)
-
-    dzdx_array = ndimage.sobel(elevation_array, axis=1) / (8. * pixel_w)
-    dzdy_array = ndimage.sobel(elevation_array, axis=0) / (8. * pixel_h)
-
-    # Slope
-    hypotenuse_array = np.hypot(dzdx_array, dzdy_array)
-    slope_array = numexpr.evaluate(
-        "arctan(hypotenuse_array) / RADIANS_PER_DEGREE")
-    slope_array[mask] = nodata_value
-    del hypotenuse_array
-
-    # Aspect
-    # Convert angles from conventional radians to compass heading 0-360
-    aspect_array = numexpr.evaluate(
-        "(450 - arctan2(dzdy_array, -dzdx_array) / RADIANS_PER_DEGREE) % 360")
-    aspect_array[mask] = nodata_value
-    del dzdx_array, dzdy_array
-
-    # save the output array into a raster
-    arcpy.NumPyArrayToRaster(slope_array, lowleft_corner, pixel_w, pixel_h,
-                             value_to_nodata=nodata_value).save(slope_fname)
-    arcpy.DefineProjection_management(slope_fname, sref)
-
-    arcpy.NumPyArrayToRaster(aspect_array, lowleft_corner, pixel_w, pixel_h,
-                             value_to_nodata=nodata_value).save(aspect_fname)
-    arcpy.DefineProjection_management(aspect_fname, sref)
-
-    del elevation_array, slope_array, aspect_array

-
- -
-
-
-
-
- - -
-
-
-
-
-

Navigation

- -
-
- © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
- - \ No newline at end of file diff --git a/docs/html/_modules/utilities/files.html b/docs/html/_modules/utilities/files.html deleted file mode 100644 index 4678e29..0000000 --- a/docs/html/_modules/utilities/files.html +++ /dev/null @@ -1,446 +0,0 @@ - - - - - - - - - - utilities.files — BAL 1.0 documentation - - - - - - - - - - - - -
-

Navigation

- -
- -
-
-
-
- -

Source code for utilities.files

-"""
-Provides utilities dealing with files.
-"""
-
-import os
-import sys
-import logging
-import datetime
-import numpy as np
-from time import ctime, localtime, strftime
-
-try:
-    import hashlib
-    md5_constructor = hashlib.md5
-except ImportError:
-    import md5
-    md5_constructor = md5.new
-
-__version__ = '$Id: files.py 685 2012-03-29 04:22:32Z carthur $'
-
-logger = logging.getLogger()
-
-if not getattr(__builtins__, "WindowsError", None):
-    class WindowsError(OSError):
-        pass
-
-
-
[docs]def fl_module_path(level=1):
-    """
-    Get the path of the module <level> levels above this function
-
-    :param int level: level in the stack of the module calling this function
-                      (default = 1, function calling ``fl_module_path``)
-
-    :returns: path, basename and extension of the file containing the module
-
-    :Example: path, base, ext = fl_module_path( ), Calling fl_module_path()
-              from "/foo/bar/baz.py" produces the result "/foo/bar", "baz",
-              ".py"
-    """
-
-    filename = os.path.realpath(sys._getframe(level).f_code.co_filename)
-    path, fname = os.path.split(filename)
-    base, ext = os.path.splitext(fname)
-    path = path.replace(os.path.sep, '/')
-    return path, base, ext
-
-

-
[docs]def fl_module_name(level=1):
-    """
-    Get the name of the module <level> levels above this function
-
-    :param int level: Level in the stack of the module calling this function
-                      (default = 1, function calling ``fl_module_name``)
-
-    :returns: Module name.
-    :rtype: str
-
-    :Example: mymodule = fl_module_name( ) Calling fl_module_name() from
-              "/foo/bar/baz.py" returns "baz"
-
-    """
-
-    package = sys._getframe(level).f_code.co_name
-    return package
-
-

-
[docs]def fl_program_version(level=None):
-    """
-    Return the __version__ string from the top-level program, where defined.
-
-    If it is not defined, return an empty string.
-
-    :param int level: level in the stack of the main script
-                      (default = maximum level in the stack)
-
-    :returns: version string (defined as the ``__version__`` global variable)
-
-    """
-
-    if not level:
-        import inspect
-        level = len(inspect.stack()) - 1
-    f = sys._getframe(level)
-    if '__version__' in f.f_globals:
-        return f.f_globals['__version__']
-    else:
-        return ''
-
-

-
[docs]def fl_load_file(filename, comments='%', delimiter=',', skiprows=0):
-    """
-    Load a delimited text file -- uses :func:`numpy.genfromtxt`
-
-    :param filename: File, filename, or generator to read
-    :type  filename: file or str
-    :param comments: (default '%') indicator
-    :type  comments: str, optional
-    :param delimiter: The string used to separate values.
-    :type  delimiter: str, int or sequence, optional
-
-    """
-
-    return np.genfromtxt(filename, comments=comments, delimiter=delimiter,
-                         skip_header=skiprows)
-
-

-
[docs]def fl_save_file(filename, data, header='', delimiter=',', fmt='%.18e'):
-    """
-    Save data to a file.
-
-    Does some basic checks to ensure the path exists before attempting
-    to write the file. Uses :class:`numpy.savetxt` to save the data.
-
-    :param str filename: Path to the destination file.
-    :param data: Array data to be written to file.
-    :param str header: Column headers (optional).
-    :param str delimiter: Field delimiter (default ',').
-    :param str fmt: Format statement for writing the data.
-
-    """
-
-    directory, fname = os.path.split(filename)
-    if not os.path.isdir(directory):
-        os.makedirs(directory)
-
-    try:
-        np.savetxt(filename, data, header=header, delimiter=delimiter,
-                   fmt=fmt, comments='%')
-    except TypeError:
-        np.savetxt(filename, data, delimiter=delimiter, fmt=fmt, comments='%')
-
-

-
[docs]def fl_get_stat(filename, chunk_whole=2 ** 16):
-    """
-    Get basic statistics of filename - namely directory, name (excluding
-    base path), md5sum and the last modified date. Useful for checking
-    if a file has previously been processed.
-
-    :param str filename: Filename to check.
-    :param int chunk_whole: (optional) chunk size (for md5sum calculation).
-
-    :returns: path, name, md5sum, modification date for the file.
-    :raises TypeError: if the input file is not a string.
-    :raises IOError: if the file is not a valid file, or if the file
-                     cannot be opened.
-
-    :Example: dir, name, md5sum, moddate = fl_get_stat(filename)
-
-    """
-
-    try:
-        fh = open(filename)
-        fh.close()
-    except:
-        logger.exception("Cannot open %s" % (filename))
-        raise IOError("Cannot open %s" % (filename))
-
-    try:
-        directory, fname = os.path.split(filename)
-    except:
-        logger.exception('Input file is not a string')
-        raise TypeError('Input file is not a string')
-
-    try:
-        si = os.stat(filename)
-    except IOError:
-        logger.exception('Input file is not a valid file: %s' % (filename))
-        raise IOError('Input file is not a valid file: %s' % (filename))
-
-    moddate = ctime(si.st_mtime)
-    m = md5_constructor()
-    f = open(filename, 'rb')
-
-    while True:
-        chunk = f.read(chunk_whole)
-        if not chunk:
-            break
-        m.update(chunk)
-    md5sum = m.hexdigest()
-
-    return directory, fname, md5sum, moddate
-
-

-
[docs]def fl_config_file(extension='.ini', prefix='', level=None):
-    """
-    Build a configuration filename (default extension .ini) based on the
-    name and path of the function/module calling this function. Can also
-    be useful for setting log file names automatically.
-    If prefix is passed, this is preprended to the filename.
-
-    :param str extension: file extension to use (default '.ini'). The
-                          period ('.') must be included.
-    :param str prefix: Optional prefix to the filename (default '').
-    :param level: Optional level in the stack of the main script
-                  (default = maximum level in the stack).
-
-    :returns: Full path of calling function/module, with the source file's
-              extension replaced with extension, and optionally prefix
-              inserted after the last path separator.
-
-    :Example: configFile = fl_config_file('.ini') Calling fl_config_file from
-              /foo/bar/baz.py should return /foo/bar/baz.ini
-    """
-
-    if not level:
-        import inspect
-        level = len(inspect.stack())
-
-    path, base, ext = fl_module_path(level)
-    config_file = os.path.join(path, prefix + base + extension)
-    config_file = config_file.replace(os.path.sep, '/')
-    return config_file
-
-

-
[docs]def fl_start_log(log_file, log_level, verbose=False, datestamp=False,
-                 newlog=True):
-    """
-    Start logging to log_file all messages of log_level and higher.
-    Setting ``verbose=True`` will report all messages to STDOUT as well.
-
-    :param str log_file: Full path to log file.
-    :param str log_level: String specifiying one of the standard Python logging
-                         levels ('NOTSET','DEBUG','INFO','WARNING','ERROR',
-                         'CRITICAL')
-    :param boolean verbose: ``True`` will echo all logging calls to STDOUT
-    :param boolean datestamp: ``True`` will include a timestamp of the creation
-                              time in the filename.
-    :param boolean newlog: ``True`` will create a new log file each time this
-                           function is called. ``False`` will append to the
-                           existing file.
-
-    :returns: :class:`logging.logger` object.
-
-    :Example: fl_start_log('/home/user/log/app.log', 'INFO', verbose=True)
-
-    """
-
-    if datestamp:
-        b, e = os.path.splitext(log_file)
-        curdate = datetime.datetime.now()
-        curdatestr = curdate.strftime('%Y%m%d%H%M')
-        # The lstrip on the extension is required as splitext leaves it on.
-        log_file = "%s.%s.%s" % (b, curdatestr, e.lstrip('.'))
-
-    log_dir = os.path.dirname(os.path.realpath(log_file))
-    if not os.path.isdir(log_dir):
-        try:
-            os.makedirs(log_dir)
-        except OSError:
-            # Unable to create the directory, so stick it in the
-            # current working directory:
-            path, fname = os.path.split(log_file)
-            log_file = os.path.join(os.getcwd(), fname)
-
-    if newlog:
-        mode = 'w'
-    else:
-        mode = 'a'
-
-    logging.basicConfig(level=getattr(logging, log_level),
-                        format='%(asctime)s: %(message)s',
-                        datefmt='%Y-%m-%d %H:%M:%S',
-                        filename=log_file,
-                        filemode=mode)
-    logger = logging.getLogger()
-
-    if len(logger.handlers) < 2:
-        # Assume that the second handler is a StreamHandler for verbose
-        # logging. This ensures we do not create multiple StreamHandler
-        # instances that will *each* print to STDOUT
-        if verbose and sys.stdout.isatty():
-            # If set to true, all logging calls will also be printed to the
-            # console (i.e. STDOUT)
-            console = logging.StreamHandler()
-            console.setLevel(getattr(logging, log_level))
-            formatter = logging.Formatter('%(asctime)s: %(message)s',
-                                          '%H:%M:%S', )
-            console.setFormatter(formatter)
-            logger.addHandler(console)
-
-    logger.info('Started log file %s (detail level %s)' % 
-                (log_file, log_level))
-    logger.info('Running %s (pid %d)' % (sys.argv[0], os.getpid()))
-    logger.info('Version %s' % (fl_program_version()))
-    return logger
-
-

-
[docs]def fl_log_fatal_error(tblines):
-    """
-    Log the error messages normally reported in a traceback so that
-    all error messages can be caught, then exit. The input 'tblines'
-    is created by calling ``traceback.format_exc().splitlines()``.
-
-    :param list tblines: List of lines from the traceback.
-
-    """
-
-    for line in tblines:
-        logger.critical(line.lstrip())
-    sys.exit()
-
-

-
[docs]def fl_mod_date(filename, dateformat='%Y-%m-%d %H:%M:%S'):
-    """
-    Return the last modified date of the input file
-
-    :param str filename: file name (full path).
-    :param str dateformat: Format string for the date (default
-                           '%Y-%m-%d %H:%M:%S')
-
-    :returns: File modification date/time as a string
-    :rtype: str
-
-    :Example: modDate = fl_mod_date( 'C:/foo/bar.csv' ,
-                                 dateformat='%Y-%m-%dT%H:%M:%S' )
-    """
-
-    try:
-        si = os.stat(filename)
-    except IOError:
-        logger.exception('Input file is not a valid file: %s' % (filename))
-        raise IOError('Input file is not a valid file: %s' % (filename))
-    moddate = localtime(si.st_mtime)
-
-    return strftime(dateformat, moddate)
-
-

-
[docs]def fl_size(filename):
-    """
-    Return the size of the input file in bytes
-
-    :param str filename: Full path to the file.
-
-    :returns: File size in bytes.
-    :rtype: int
-
-    :Example: file_size = fl_size( 'C:/foo/bar.csv' )
-    """
-
-    try:
-        si = os.stat(filename)
-    except WindowsError:
-        logger.exception('Input file is not a valid file: %s' % (filename))
-        raise IOError('Input file is not a valid file: %s' % (filename))
-    except IOError:
-        logger.exception('Input file is not a valid file: %s' % (filename))
-        raise IOError('Input file is not a valid file: %s' % (filename))
-    else:
-        size = si.st_size
-
-    return size

-
- -
-
-
-
-
- - -
-
-
-
-
-

Navigation

- -
-
- © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
- - \ No newline at end of file diff --git a/docs/html/_sources/docs/background.txt b/docs/html/_sources/docs/background.txt deleted file mode 100644 index 1248531..0000000 --- a/docs/html/_sources/docs/background.txt +++ /dev/null @@ -1,59 +0,0 @@ -Background -============ - -The algorithm used to calculate the BAL is based on Method 1 in the Australian Standard AS 3959 (2009)--*Construction of buildings in bushfire-prone areas*. - -Method 1 is a simplified procedure that involves five steps to determine BAL, and is subject to limitations on the circumstances in which it can be used. - -**Limitation**: This method doesn't apply to the circumstances where the effective slope under the classified vegetation is more than 20 degrees downslope. - -Procedure to determine BAL --------------------------- - -According to the Standard AS 3959 (2009), five steps are involved to calculate BAL. - -**Step 1:** Select the relevant FDI based on the locations according to Table 2.1 in the Australian Standard AS 3959 (2009). For example, from Table 2.1, the FDI for Western Australia is 80. - -**Step 2:** Reclassify the input vegetation dataset into seven vegetation types defined in Table 2.3 in the Standard AS 3959 (2009). - -* 1: Forest, -* 2: Woodland, -* 3: Shrubland, -* 4: Scrub, -* 5: Mallee/Mulga, -* 6: Rainforest, -* 7: Grassland/Tussock moorland. - -The numbers from 1 to 7 are assigned to these vegetation classes respectively for calculating BAL. - -**Step 3:** Calculate the distance of the site from the classified vegetation. According to AS 3959 (2009), the vegetation is considered when its distance from the site of interest is within 100 metres. - -**Step 4:** Determine the effective slopes (the gradient from each cell) and their aspects under the classified vegetation types. If a slope's aspect is in the same direction as the vegetation from the site, this slope is regarded as a downslope that will be further analysed. Otherwise the slope is regarded as an upslope. - -When calculating BAL, upslopes and flat lands are treated as a single category. For downslopes, the Standard breaks them down into five classes: - -* 0 < downslope <= 5 degrees -* 5 < downslope <= 10 degrees -* 10 < downslope <= 15 degrees -* 15 < downslope <= 20 degrees -* > 20 degrees (beyond consideration of Method 1) - -**Step 5:** Determine the BAL from an appropriate table defined in AS 3959 (2009) based on the input FDI. For example, for Western Australia, the FDI is 80 and thus Table 2.4.3 is adopted for deriving the BAL. - -Deriving and interpreting BAL ------------------------------ - -We consider eight cardinal directions: north, northeast, east, southeast, south, southwest, west, and northwest. - -For each cardinal direction, we consider the neighbouring cells up to 100 metres from the site. We calculate the BAL for each neighbouring cell with regards to the site based on the neighbouring cell's vegetation type, upslope or downslope degrees, and its distance to the site. - -The BAL falls into a list of (12.5, 19, 29, 40, 100), where 100 represents Fire Zone (FZ). There is one more circumstances beyond Method 1 in AS 3959 (2009). - -* Where the downslope is greater than 20 degrees and there is vegetation, a constant value of 200 is given to the BAL. - -The maximum BAL is selected among all neighbouring cells in a given cardinal direction to represent the BAL for that direction. - -The final BAL for the site of interest is determined by selecting the maximum BAL from all eight cardinal directions. - - - diff --git a/docs/html/_sources/docs/bal.txt b/docs/html/_sources/docs/bal.txt deleted file mode 100644 index effe5d6..0000000 --- a/docs/html/_sources/docs/bal.txt +++ /dev/null @@ -1,14 +0,0 @@ - - -Bushfire Attack Level -********************* - - - -bal.py -=========================================== - -.. automodule:: bal - :members: - - diff --git a/docs/html/_sources/docs/calculate_bal.txt b/docs/html/_sources/docs/calculate_bal.txt deleted file mode 100644 index 4078750..0000000 --- a/docs/html/_sources/docs/calculate_bal.txt +++ /dev/null @@ -1,14 +0,0 @@ - - -Calculate_bal -************** - - - -calculate_bal.py -=========================================== - -.. automodule:: calculate_bal - :members: - - diff --git a/docs/html/_sources/docs/disclaim.txt b/docs/html/_sources/docs/disclaim.txt deleted file mode 100644 index 46fb392..0000000 --- a/docs/html/_sources/docs/disclaim.txt +++ /dev/null @@ -1,9 +0,0 @@ -Disclaimer -========== - -Geoscience Australia has tried to make the information in this product as accurate as possible. However, it does not guarantee that the information produced by this product is totally accurate or complete. Therefore, users should use the BAL values derived from the BAL toolbox as an indicative guide only, and should not solely rely on this information when making a decision. - -This work was produced at Geoscience Australia. Neither the Australian Government, Geoscience Australia nor any of their employees, makes any warranty, express or implied, or assumes any liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately-owned rights. Reference herein to any specific commercial products, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the Australian Government or Geoscience Australia. The views and opinions of authors expressed herein do not necessarily state or reflect those of the Australian Government or Geoscience Australia, and shall not be used for advertising or product endorsement purposes. - -This document does not convey a warranty, express or implied, of merchantability or fitness for a particular purpose. - diff --git a/docs/html/_sources/docs/evaluation.txt b/docs/html/_sources/docs/evaluation.txt deleted file mode 100644 index 913f131..0000000 --- a/docs/html/_sources/docs/evaluation.txt +++ /dev/null @@ -1,84 +0,0 @@ -Evaluation -========== - -TCRM provides functionality to evaluate the performance of the track -model over the model domain through the :mod:`Evaluate` module. By -running a number of simulations, each generating a similar number of -years of events to the input track database, we can compare the -synthetic events with the observations. Metrics include track density, -genesis distribution, minimum pressure distributions, landfall rates -and longitude crossing rates. - - -Setup ------ - -An example configuration for executing an evaluation. Other sections -of the configuration file should remain unchanged. :: - - [Actions] - DataProcess=True - ExecuteStat=True - ExecuteTrackGenerator=True - ExecuteWindfield=False - ExecuteHazard=False - PlotHazard=False - PlotData=False - ExecuteEvaluate=False - DownloadData=True - - [Input] - LandMask=input/landmask.nc - MSLPFile=MSLP/slp.day.ltm.nc - CoastlineGates=input/gates.txt - - [TrackGenerator] - NumSimulations=500 - YearsPerSimulation=30 - NumTimeSteps=360 - TimeStep=1.0 - SeasonSeed=1 - TrackSeed=1 - -Note that the ``YearsPerSimulation`` option is now set to 30, so TCRM -will generate 500 event sets, each with the equivalent of 30 years of -TCs. The annual frequency of events is based on a Poisson distribution -around the mean annual frequency, which is determined from the input -track database. - -A csv-format file containing a set of gates around the coastline is -required for :mod:`Evaluate.landfallRates`. Gates are defined as a -series of points around the coastline in number, longitude, latitude -format. Below are the first 15 points in the sample gates provided in -the code base. :: - - 0.00, 114.78, -34.70 - 1.00, 115.20, -32.95 - 2.00, 114.90, -31.17 - 3.00, 114.49, -29.42 - 4.00, 113.66, -27.83 - 5.00, 112.73, -26.28 - 6.00, 112.96, -24.50 - 7.00, 113.22, -22.72 - 8.00, 114.47, -21.43 - 9.00, 115.98, -20.44 - 10.00, 117.74, -20.08 - 11.00, 119.46, -19.55 - 12.00, 121.12, -18.84 - 13.00, 121.74, -17.15 - 14.00, 123.04, -15.91 - 15.00, 124.49, -14.85 - -Output ------- - -The :mod:`Evaluate` module generates a set of figures that compare the -synthetic event set to the input track database. For the synthetic -events, the module calculates a mean value and upper and lower -percentiles of the distribution (commonly the 5th and 95th percentile -values). - -Some of the results are also saved to netCDF files (track density, -pressure distributions and longitude crossing rates) for users to -import into other graphics packages. - diff --git a/docs/html/_sources/docs/examples.txt b/docs/html/_sources/docs/examples.txt deleted file mode 100644 index f5a9c3d..0000000 --- a/docs/html/_sources/docs/examples.txt +++ /dev/null @@ -1,80 +0,0 @@ -An Example -========== - -Input ------ - -**Input DEM:** - -jerram_dem: Esri Grid format, MGA 50, 25 m resolution. See Figure 4.8. The input DEM is located under the **examples\\input** folder. - -.. figure:: dem_example.jpg - :align: center - :alt: Example DEM data at Jerramungup, WA. - :figclass: align-center - - Example DEM data at Jerramungup, WA. - -**Input vegetation:** - -jerram_veg: Esri Grid format, GDA 1994 Australia Albers, 100 m resolution. See Figure 4.9. The input vegetation dataset is located under the **examples\\input** folder. - -.. figure:: veg_example.jpg - :align: center - :alt: Example vegetation data at Jerramungup, WA. - :figclass: align-center - - Example vegetation data at Jerramungup, WA. - - -**Input vegetation reclassification map:** - -There are many classes in the original vegetation. To derive the target vegetation classes described in the Standard (1: Forest, 2: Woodland, 3: Shrubland, 4: Scrub, 5: Mallee/Mulga, 6: Rainforest, 7: Grassland/Tussock moorland.), the remap string is defined as: "1 6;2 1;3 1;4 1;5 13 2;14 5;15 18 3;19 22 7;23 4;24 25 NODATA;26 4;27 28 NODATA;29 4;30 1;31 2;32 5;99 NODATA". - - -**Output path:** - -The example output path is C:\\github\\bal\\examples\\output. - -**FDI value:** - -Default value 80 is selected. - -**Extent:** - -Default is selected. - -After all input parameters are defined, the fields in the BAL calculation window are all populated. See Figure 4.10. - -.. figure:: example_BAL_calculation.jpg - :align: center - :alt: Example input parameters within BAL calculation window. - :figclass: align-center - - Example input parameters within BAL calculation window. - -Process -------- - -After clicking the **OK** button in the above window, the calculation starts running with a progress reporting in a pop-up window. When it finishes successfully, the pop-up window looks like Figure 4.11. - -.. figure:: example_process.jpg - :align: center - :alt: Example pop-up window when the calculation finishes. - :figclass: align-center - - Example pop-up window when the calculation finishes. - - -Output ------- -Nine rasters are produced under C:\\github\\bal\\examples\\output. Figure 4.12 displays the maximum BAL raster file named as bal_max.img for this example. - -.. figure:: bal_max.jpg - :align: center - :alt: Example output BAL at Jerramungup, WA. - :figclass: align-center - - Example output BAL at Jerramungup, WA. - - \ No newline at end of file diff --git a/docs/html/_sources/docs/execution.txt b/docs/html/_sources/docs/execution.txt deleted file mode 100644 index 00513b2..0000000 --- a/docs/html/_sources/docs/execution.txt +++ /dev/null @@ -1,92 +0,0 @@ -.. |beta| unicode:: U+003B2 .. GREEK SMALL LETTER BETA - -.. _execution: - -================ -Running the tool -================ - -To calculate the BAL, we use the **BAL calculation** tool within the **BAL** toolbox installed in ArcGIS 10.2. - -Select the **BAL calculation** tool within the **BAL** toolbox, see Figure 4.5. - -.. figure:: select_bal.jpg - :align: center - :alt: Select the tool **BAL calculation**. - :figclass: align-center - - Select the tool **BAL calculation**. - -Then the **BAL calculation** window is open, see Figure 4.6. - -.. figure:: BAL_calculation_window.jpg - :align: center - :alt: The **BAL calculation** window. - :figclass: align-center - - The **BAL calculation** window. - -Parameters within the tool -========================== - -**Input DEM raster:** - - Open the input DEM file from a specific location. The DEM is required to be in a projected coordinate system with linear unit metre. For example GDA94 / MGA zone 50 is a projected spatial reference system and is suitable for use in the western part of Western Australia. More information about GDA94 / MGA zone 50 can be found `here `_. - -**Input vegetation raster:** - - Open the input vegetation dataset from the location same as the input DEM. The vegetation dataset can be in either a geographical or a projected coordinate system. It will be reprojected to the same projection and same resolution as DEM by the BAL tool. - -**Vegetation reclassification:** - - Reclassify the input vegetation classes into those defined in the Australian Standard AS 3959 (2009). There are seven classes defined in the Standard. In this tool, we give each class a unique number, i.e.: - - * 1: Forest, - * 2: Woodland, - * 3: Shrubland, - * 4: Scrub, - * 5: Mallee/Mulga, - * 6: Rainforest, - * 7: Grassland/Tussock moorland. - - A sample reclassification map is entered for the example data. The reclassification map needs to be changed by the users according to their own input vegetation data. - -**Output path:** - - Define the output location. - -**FDI value:** - - The input Fire Danger Index (FDI) value has four choices (100, 80, 50, 40) based on the locations, which are specified in the Australian Standard AS 3959 (2009). - - * 100: Australian Capital Territory (ACT), part of New South Wales (NSW) (Greater Hunter, Greater Sydney, Illawarra/Shoalhaven, Far South Coast and Southern Ranges fire weather districts), and Victoria general (excluding alpine areas). - * 80: NSW general (excluding alpine areas, and the areas with FDI 100), South Australia (SA), and Western Australia (WA). - * 50: NSW alpine areas, Tasmania, and Victoria alpine areas. - * 40: Northern Territory (NT), and Queensland (Qld). - - Select the FDI value from a suite of values (100, 80, 50, 40). It is optional. The default value is 80 that is applicable in Western Australia. - -**Extent:** - - The extent is used to select the area of interest for which BAL will be calculated. The output data extent will be where you have consistent coverage of DEM and vegetation data within the area of interest. - -**Note:** - -* There is a limitation in raster file name length and file path length in ArcGIS. For a raster name in ESRI Grid format, the maximum number of characters is 13 and for full path name, the maximum number of character is 128. For more information, `click here `_. In addition, as tested, each folder name's length should be restricted to at most eight characters. - -* The script requires that the input DEM and vegetation dataset are in the same location. The tool will fail to run when the input DEM and vegetation datasets are not in the same folder. - - -Output -====== - -A suite of rasters are produced and stored in the output folder. They represent the BAL for the area computed in each of eight cardinal directions (E, S, W, N, NE, NW, SE and SW) and the maximum BAL of all directions. Figure 4.7 is an example output. - -.. figure:: BAL_output.jpg - :align: center - :alt: An example BAL output window. - :figclass: align-center - - An example BAL output window. - - diff --git a/docs/html/_sources/docs/glossary.txt b/docs/html/_sources/docs/glossary.txt deleted file mode 100644 index f02aeb5..0000000 --- a/docs/html/_sources/docs/glossary.txt +++ /dev/null @@ -1,44 +0,0 @@ -Glossary -======== - -.. glossary:: - - Annual Exceedance Probability - The probability of a threshold being exceeded once (or more) in any - year. - - Genesis - Formation of a tropical cyclone event. - - Hazard - The magnitude of wind speed. TCRM generates a 3-second gust wind - speed, at 10 metres above ground over open, flat terrain (an - aerodynamic roughness length of 0.02 m). - - Kernel density estimation - A non-parametric method to estimate the probability density - function of a random variable. - - Lysis - Termination of a tropical cyclone event. Can be caused by the tropical - cyclone weakening through stochastic process, landfall decay or exiting - the defined domain. - - mpirun - mpirun is a runtime environment for the Message Passing Interface (MPI). - See http://www.mcs.anl.gov/research/projects/mpi/ - - Pypar - PyPar is a python library that provides efficient and scalable - parallelism using the message passing interface (MPI) to handle - big data and highly computational problems. See - http://github.com/daleroberts/pypar - - Return period - The average time between exceedances of a given threshold. Compare to - Annual Exceedance Probability. - - Tropical cyclone - A tropical cyclone is a rapidly-rotating storm system characterized by - a low-pressure center, strong winds, and a spiral arrangement of - thunderstorms that produce heavy rain. diff --git a/docs/html/_sources/docs/install.txt b/docs/html/_sources/docs/install.txt deleted file mode 100644 index 1e7a104..0000000 --- a/docs/html/_sources/docs/install.txt +++ /dev/null @@ -1,42 +0,0 @@ -Installation -============ - -Installing BAL Toolbox is intended to be a simple process, requiring only basic understanding of ArcGIS toolbox operations. It has been installed and tested on ArcGIS 10.2. - - -Unzipping the toolbox ---------------------- - -The software package is delivered as a compressed zip file. Unzip the toolbox into a location on your computer, for example C:\\bal. Then you will have stored all the files at folder C:\\bal. - - -Dependencies ------------- - -This toolbox is developed and tested within ArcGIS 10.2 that integrates with Python 2.7 and Numpy 1.6.2. It is not recommended to install an independent version of Python for use in ArcGIS. Using a different version of Python may lead to compatibility issues. - -However, if necessary, there are several ways to obtain the required libraries -- using Python's recommended tool `pip -`_, installing a distribution such as `Python(x,y) package `_ (for Windows environments), or installing the libraries from source or binary installers (pre-compiled binary Windows installer versions for all the libraries (both 32-bit and 64-bit) can be obtained `here `_). - -For detailed instructions on installation of these dependencies, please see the documentation for each individual library. - -* `Python `_ - v2.7 preferred -* `Numpy `_ - v1.6.2 preferred -* `Arcpy in ArcGIS 10.2 `_ - -Setting the environment ------------------------ -To enable BAL toolbox to run flawlessly, you may need to change some environment settings. The important variable to set is the ``PYTHONPATH`` variable. This should be set to the path where you have extracted the contents of the zip file. A complete discussion on environment variables in Python is given in the `Python documentation `_. - -Windows -~~~~~~~ -The Python documentation contains some simple instructions for setting environment variables on Windows systems `here `_. See `this link `_ for setting the variables on different Windows systems. - -Testing the installation ------------------------- - -The code includes a suite of unit tests that ensure elements of the code base work as expected. The code should be tested before running the toolbox. - -The test suite can be run from the main directory. On Windows, run the ``run_test_all.cmd`` script from the main BAL directory. - - diff --git a/docs/html/_sources/docs/intro.txt b/docs/html/_sources/docs/intro.txt deleted file mode 100644 index f6f6651..0000000 --- a/docs/html/_sources/docs/intro.txt +++ /dev/null @@ -1,45 +0,0 @@ -Introduction -============ - -Fire is a natural feature of the Australian landscape and remains an ever-present threat. Bushfire threat analysis aims to inform the fire authorities and the community of the bushfire hazard in an effort to manage the risk posed to life, property and the environment. - -Bushfire Attack Level (BAL) is a measure of the severity of a building's potential exposure to bushfire. It is defined in the Australian Standard AS 3959 (2009)--*Construction of buildings in bushfire-prone areas*, to serve as a basis for establishing the requirements for construction, to improve the protection of buildings from bushfire attack. The Standard describes how to compute the bushfire attack level for any location and directly links this to recommendations on the design of existing or planned buildings. - -The BAL toolbox implements the rules described by Method 1 in AS 3959 (2009) by integrating them into a computational code that can be run in the ESRI ArcGIS 10.2 environment. - - -Package structures ------------------- - -The toolbox name is **BAL.tbx**. This toolbox is associated with a python script, **bal.py**, to derive BAL. The script **bal.py** links to a python script **calculate_bal.py** and a module **Utilities**, which includes supporting dictionaries defined in two python scripts: - -* value_lookup.py; -* bal_database.py. - -There are three more folders: - -* **docs**: holding the documentation files. - -* **tests**: holding the unit tests, scenario tests and their test data. - -* **examples**: holding the example input and output data. - - -Use limitations ---------------- - -The BAL tool developed in Geoscience Australia (GA) has been developed and tested in ArcGIS 10.2. However, GA does not guarantee that the information derived is totally accurate or complete. Therefore, you should not solely rely on this information. Key limitations/approximations include the following: - -* The BAL is produced based on the simplified method (Method 1) in AS 3959 (2009). When the land downslope is more than 20 degrees, more detailed method (Method 2) should be adopted. Method 2 has not been incorporated into the toolbox developed. Instead, a constant value of 200 is provided as BAL for such circumstances. - -* Elevation data is a critical input of the tool. Digital Elevation Model (DEM) with finer resolution usually leads to more accurate BAL results. The example data uses a DEM with a resolution of 1 second of arc (approximate 30 m by 30 m grid cell at the equator), the best available national scale elevation dataset at the time of modelling. As with all spatial analyses, the results are sensitive to the input DEM's quality, resolution, coverage and currency and should therefore be used with this understanding. - -* Vegetation data is another critical input into the tool. Method 1 in AS 3959 (2009) considers the vegetation up to 100 metres from the site of interest. Ideally the vegetation with finer resolution (preferred at metre level) is required to derive sensible BAL analyses. Where finer vegetation data is not available, the alternative coarse vegetation data may lead to inaccurate output BAL. - -* The BAL toolbox is intended to run in the ArcGIS toolbox environment and is not intended to run in a Python script environment. - -* This software algorithm adapts to the Method 1 in AS 3959 (2009) by modelling it spatially. Readers are assumed to be familiar with AS 3959 (2009). For the detailed description of the Method 1, please refer to the Standard AS 3959 (2009). - - - - diff --git a/docs/html/_sources/docs/scenarios.txt b/docs/html/_sources/docs/scenarios.txt deleted file mode 100644 index 8b17349..0000000 --- a/docs/html/_sources/docs/scenarios.txt +++ /dev/null @@ -1,207 +0,0 @@ -.. _scenariomodelling: - -Scenario modelling -================== - -TCRM can also be used to simulate the wind field from an individual -event. Given the track of a tropical cyclone, users can run the -:mod:`wind` module only, and generate the maximum wind swath from a -TC. The `tcevent.py` script enables users to efficiently run a -scenario simulation, including performing temporal interpolation of -the track positions to generate a realistic representation of the wind -field. This can be useful for exploring synthetic events in more -detail, or for analysing the wind field from an historical tropical -cyclone. - -TCRM does not currently account for local landscape effects on wind -speed (e.g. topographic enhancement or changes in surface roughness -due to vegetation or built environments). Users should determine the -best way to include these effects for their own purposes. - -As TCRM uses a parametric profile, the primary vortex is axisymmetric, -and asymmetry in the surface winds arises solely due to the forward -motion of the cyclone and the (uniform) surface friction. For a -complete and accurate representation of the winds from an actual -tropical cyclone, the simulated winds from TCRM should be combined -with observed maximum wind speeds in the vicinity of the cyclone using -spatial interpolation methods (e.g. kriging). - -.. _scenariosetup: - -Setting up a scenario ---------------------- - -Track file requirements -~~~~~~~~~~~~~~~~~~~~~~~ - -Simulating an individual event requires details of the track of the -cyclone. As a minimum, a track file must contain the following fields: -``index``, ``indicator`` or ``tcserialno`` (to uniquely identify an -event); date/time information (either as a single field, or as -individual components); latitudel; longitude; central pressure and -radius to maximum winds. - -The ``index`` field (or the alternatives) is required as the software -uses the same methods to read the source data for both individual -events and best-track databases that contain many events. The example -configuration below uses an ``index`` field, with ``1`` in the first -row and ``0`` in all subsequent rows. - -The radius to maximum wind is required in individual events, as it -cannot be artificially generated, as is the case in the generation of -synthetic events. - -Configuration -~~~~~~~~~~~~~ - -Users will need to manually edit a configuration file to execute a -scenario simulation. Many of the options in the main TCRM -configuration file are not required for scenario simulation, so it is -recommended to create a reduced configuration file that contains only -the required sections and options. - -A basic configuration file for a scenario simulation would look like -this:: - - [DataProcess] - InputFile = scenario.csv - Source = NRL - FilterSeasons = False - - [WindfieldInterface] - Margin = 3 - Resolution = 0.02 - profileType = powell - windFieldType = kepert - - [Timeseries] - Extract = True - StationFile = ./input/stationlist.shp - StationID = WMO - - [Input] - landmask = input/landmask.nc - mslpfile = MSLP/slp.day.ltm.nc - - [Output] - Path = ./output/scenario - - [NRL] - Columns = index,skip,skip,date,lat,lon,skip,skip,pressure,rmax - FieldDelimiter = , - NumberOfHeadingLines = 0 - PressureUnits = hPa - SpeedUnits = kts - LengthUnits = km - DateFormat = %Y%m%d %H:%M - - [Logging] - LogFile = output/scenario/log/scenario.log - LogLevel = INFO - Verbose = True - NewLog = True - DateStamp = True - - -.. _runningscenario: - -Running the scenario --------------------- - -The `tcevent.py` script loads the track file, performs the temporal -interpolation and then passes the interpolated track file to the -:mod:`wind` module. Since the ``Region`` section has been removed, the -:meth:`wind.run` method will set the grid domain to cover the entire -extent of the track. - -Make sure ``python`` is in your system path, then from the base -directory, call the ``tcevent.py`` script, with the configuration -file option included. For example, to run the example scenario:: - - python tcevent.py -c example/scenario.ini - -If the ``-v`` option is included, then all logging messages will be -printed to the console. The level of logging detail is set in the -configuration file. - -:Note: `tcevent.py` cannot be executed in parallel. - -.. _scenariocmdlineargs: - -Command line arguments ----------------------- - - -c file, --config file Path to a configuration file. - -v, --verbose If given, logging messages will be printed - to the console. - -d, --debug In the case that execution results in an exception, - allow the Python stack to call into the stack trace - (through implementation of a custom hook script) and - start the Python debugger (:mod:`pdb`). - -.. _timeseries: - -Extract time series data ------------------------- - -When running a scenario, it is possible to extract a time series of -the wind speed and sea level pressure values from the grid at selected -locations. The locations are defined in a user-supplied point shape -file (a location database is planned for inclusion in future -versions to better facilitate this feature). The shape file should -contain a field with a unique identifier, otherwise station output is -numbered sequentially through the locations. - -* Locations must be provided in geographic coordinates (longitude, - latitude coordinates). No reprojection is performed. -* Output is a 'regional' wind speed -- that is, the wind speed at that - location, excluding local topographic or landscape effects. These - effects can be incorporated offline (i.e. outside the TCRM - framework). - -The data is stored in a separate csv file for each location, and data -is plotted on a simple figure for visual inspection. - -.. figure:: ./maxwind_example.png - :align: center - :alt: Maximum wind speed swath of Typhoon *Haiyan* - :figclass: align-center - - Estimated maximum wind speed swath of Super Typhoon - *Haiyan* (2013) across the Philippine archipelago. This simulation - used the best track estimate from the Joint Typhoon Warning Center - to establish the intensity and radius to maximum winds of the - typhoon. No attempt is made to fit the radial profile to defined - wind radii (e.g. radius of 46-, 50- or 34-knots). - -.. figure:: ./timeseries_example.png - :align: center - :alt: Time series example from Guiuan, Philippines - :figclass: align-center - - Time series data for Super Typhoon *Haiyan* at Guiuan, Samar, Philippines. - -:Note: The double labels on the secondary (right-hand) y-axis require - Matplotlib version 1.3 or later. - -Troubleshooting ---------------- - -Some common errors when running a scenario. - -``MemoryError`` -~~~~~~~~~~~~~~~ - -In isolated cases, ``tcevent.py`` may fail and report a message that -ends with ``MemoryError``. This arises when the size of arrays in -Python exceed 2GB (on 32-bit systems). Conditions that lead to this -error are not clear. To resolve the problem, it is recommended to -reduce the domain of the wind field by adding a ``Region`` section to -the configuration file.:: - - [Region] - gridLimit = {'xMin':118., 'xMax':122., 'yMin':-23., 'yMax':-17.} - -This will restrict calculation of the wind field to the defined -domain. The ``gridLimit`` value is described in the -:ref:`configureregion` section. diff --git a/docs/html/_sources/docs/setup.txt b/docs/html/_sources/docs/setup.txt deleted file mode 100644 index ac0e3e7..0000000 --- a/docs/html/_sources/docs/setup.txt +++ /dev/null @@ -1,53 +0,0 @@ -.. |beta| unicode:: U+003B2 .. GREEK SMALL LETTER BETA - -.. _setup: - -====================== -Setting up the toolbox -====================== - -Adding the toolbox into ArcGIS 10.2 ------------------------------------ - -Follow the steps below to add the toolbox into ArcGIS 10.2: - -* Open the ArcToolBox window. See Figure 4.1. - -.. figure:: arctoolbox.jpg - :align: center - :alt: ArcToolbox window. - :figclass: align-center - - The ArcToolbox window. - -* Right click **ArcToolbox** at the top of the window, see Figure 4.2. - -.. figure:: rightclick_arctoolbox.jpg - :align: center - :alt: Right click ArcToolbox in the ArcToolbox window. - :figclass: align-center - - Right click **ArcToolbox** in the ArcToolbox window. - -* Select **Add Toolbox...**, a dialog box is open. See Figure 4.3. - -.. figure:: addtoolbox_dialog.jpg - :align: center - :alt: addtoolbox dialog window. - :figclass: align-center - - The **Add Toolbox** dialog window. - -* In the dialog box, navigate to the location of the package, for example C:\\bal, you will find the **BAL.tbx**. See Figure 4.3. - - -* Select **BAL.tbx** and click **Open**, a new toolbox called **BAL** is added to the ArcToolbox. See Figure 4.4. - -.. figure:: BAL_toolbox.jpg - :align: center - :alt: Bal toolbox is added. - :figclass: align-center - - The **Bal** toolbox is added. - - diff --git a/docs/html/_sources/docs/sources.txt b/docs/html/_sources/docs/sources.txt deleted file mode 100644 index 9599989..0000000 --- a/docs/html/_sources/docs/sources.txt +++ /dev/null @@ -1,115 +0,0 @@ - -.. _sourceformats: - -============================================== -Using different TC databases - source formats -============================================== - -There are a wide variety of formats of tropical cyclone track -databases available, both observational and model generated (e.g. we -have used tropical cyclone-like vortices derived from regional and -global climate models). To introduce users to the model, we include -the format for the `International Best Tracks Archive for Climate -Stewardship `_ (IBTrACS-WMO -format). The default action for TCRM is to download the current -version (v03r05 at August 2014) and use this to calibrate the model. - -.. _requiredfields: - -Required fields ---------------- -As a bare minimum, TCRM requires data on the date/time, longitude, -latitude, central pressure of each cyclone observation. It also -requires a field that indicates each unique TC event in the -database. This can be a ``tcserialno`` - a unique string for each -event; a TC ``num`` which is an integer value for each event in a -season; or an ``indicator`` field, which is set to ``1`` for the first -observation of a new TC, and ``0`` otherwise. - -For individual scenario modelling, an additional field containing the -radius to maximum winds (``rmax``) must be included. - -.. _databaseformat: - -Database format -------------------- - -The first few lines of the IBTrACS database are shown below. :: - - IBTrACS WMO: International Best Tracks Archive for Climate Stewardship -- WMO DATA ONLY -- Version: v03r05 - Serial_Num,Season,Num,Basin,Sub_basin,Name,ISO_time,Nature,Latitude,Longitude,Wind(WMO),Pres(WMO),Center,Wind(WMO) Percentile,Pres(WMO) Percentile,Track_type - N/A,Year,#,BB,BB,N/A,YYYY-MM-DD HH:MM:SS,N/A,deg_north,deg_east,kt,mb,N/A,%,%,N/A - 1848011S09080,1848,02, SI, MM,XXXX848003,1848-01-11 06:00:00, NR, -8.60, 79.80, 0.0, 0.0,reunion,-100.000,-100.000,main - 1848011S09080,1848,02, SI, MM,XXXX848003,1848-01-12 06:00:00, NR, -9.00, 78.90, 0.0, 0.0,reunion,-100.000,-100.000,main - 1848011S09080,1848,02, SI, MM,XXXX848003,1848-01-13 06:00:00, NR,-10.40, 73.20, 0.0, 0.0,reunion,-100.000,-100.000,main - 1848011S09080,1848,02, SI, MM,XXXX848003,1848-01-14 06:00:00, NR,-12.80, 69.90, 0.0, 0.0,reunion,-100.000,-100.000,main - 1848011S09080,1848,02, SI, MM,XXXX848003,1848-01-15 06:00:00, NR,-13.90, 68.90, 0.0, 0.0,reunion,-100.000,-100.000,main - 1848011S09080,1848,02, SI, MM,XXXX848003,1848-01-16 06:00:00, NR,-15.30, 67.70, 0.0, 0.0,reunion,-100.000,-100.000,main - 1848011S09080,1848,02, SI, MM,XXXX848003,1848-01-17 06:00:00, NR,-16.50, 67.00, 0.0, 0.0,reunion,-100.000,-100.000,main - 1848011S09080,1848,02, SI, MM,XXXX848003,1848-01-18 06:00:00, NR,-18.00, 67.40, 0.0, 0.0,reunion,-100.000,-100.000,main - -.. _configuringsource: - -Setting the configuration options ---------------------------------- - -The columns arrangement can be determined from looking at the second -line of the database: -``Serial_Num,Season,Num,Basin,Sub_basin,Name,ISO_time,Nature,Latitude,Longitude,Wind(WMO),Pres(WMO),Center,Wind(WMO) -Percentile,Pres(WMO) Percentile,Track_type``. The important variables -required for TCRM are the ``Serial_Num``, ``ISO_time``, ``Latitude``, -``Longitude`` and ``Pres(WMO)`` columns. All other variables can be -ignored. Based on this, the ``Columns`` option can be set as:: - - Columns = tcserialno,season,num,skip,skip,skip,date,skip,lat,lon,skip,pressure - -Notice that there are only 12 columns specified, but the database -contains 15 columns. The last three columns are not used, so since -they are not specified, they are automatically ignored. - -The data are comma-delimited, so the ``FieldDelimiter`` option is set -to a comma -- it does not need to be wrapped in quotes. :: - - FieldDelimiter = , - - -The first three lines are metadata and information that describe the -data (version, column names, units). These lines are ignored when the -``NumberOfHeadingLines`` option is set to 3. :: - - NumberOfHeadingLines = 3 - -The format of the date field needs to be specified in the -configuration file. Format specification is controlled by Python's -standard :mod:`datetime` module. :: - - DateFormat = %Y-%m-%d %H:%M:%S - - -The remaining three options -- ``PressureUnits``, ``LengthUnits`` and -``SpeedUnits`` -- set the units of the pressure values, any length -units and the speed units (of motion of the storms). Notice that the -third line in the database indicates the wind speed is in units of -``kt`` (knots) - this refers to the observed maximum wind speed. The -``SpeedUnits`` option controls the units for the forward motion speed -of storms - a field that is not included in the IBTrACS database. :: - - PressureUnits = hPa - LengthUnits = km - SpeedUnits = kmh - - -The full section for using IBTrACS is shown below. :: - - [IBTRACS] - ; Input data file settings - URL = ftp://eclipse.ncdc.noaa.gov/pub/ibtracs/v03r05/wmo/csv/Allstorms.ibtracs_wmo.v03r05.csv.gz - Path = input - Filename = Allstorms.ibtracs_wmo.v03r05.csv - NumberOfHeadingLines = 3 - Columns = tcserialno,season,num,skip,skip,skip,date,skip,lat,lon,skip,pressure - FieldDelimiter = , - DateFormat = %Y-%m-%d %H:%M:%S - PressureUnits = hPa - LengthUnits = km - SpeedUnits = kph diff --git a/docs/html/_sources/docs/tests.txt b/docs/html/_sources/docs/tests.txt deleted file mode 100644 index 6ce5e46..0000000 --- a/docs/html/_sources/docs/tests.txt +++ /dev/null @@ -1,149 +0,0 @@ - -tests -********************** - -__init__.py -=========================================== - - -.. automodule:: __init__ - :members: - - - -test_all_neighb.py -=========================================== - - -.. automodule:: test_all_neighb - :members: - - -test_bal_cal.py -=========================================== - - -.. automodule:: test_bal_cal - :members: - - -test_bal_class.py -=========================================== - - -.. automodule:: test_bal_class - :members: - - - -test_bal_esti.py -=========================================== - - -.. automodule:: test_bal_esti - :members: - - - -test_convo.py -=========================================== - - -.. automodule:: test_convo - :members: - - -test_dist_limit.py -=========================================== - - -.. automodule:: test_dist_limit - :members: - - - -test_find_common_area.py -=========================================== - - -.. automodule:: test_find_common_area - :members: - - - -test_find_dist_class.py -=========================================== - - -.. automodule:: test_find_dist_class - :members: - - -test_findAOI.py -=========================================== - - -.. automodule:: test_findAOI - :members: - - - -test_get_extent_mask.py -=========================================== - - -.. automodule:: test_get_extent_mask - :members: - - - -test_get_slope_aspect.py -=========================================== - - -.. automodule:: test_get_slope_aspect - :members: - - - -test_get_slope_in_aspect.py -=========================================== - - -.. automodule:: test_get_slope_in_aspect - :members: - - - -tes_point_c.py -=========================================== - - -.. automodule:: test_point_c - :members: - - -test_point_r.py -=========================================== - - -.. automodule:: test_point_r - :members: - - -test_reclass_veg.py -=========================================== - - -.. automodule:: test_reclass_veg - :members: - - - -test_scenario.py -=========================================== - - -.. automodule:: test_scenario - :members: - diff --git a/docs/html/_sources/docs/use_limit.txt b/docs/html/_sources/docs/use_limit.txt deleted file mode 100644 index 39f929f..0000000 --- a/docs/html/_sources/docs/use_limit.txt +++ /dev/null @@ -1,23 +0,0 @@ -Introduction -============ - -Fire is a natural feature of the Australian landscape and remains an ever-present threat. Bushfire threat analysis aims to inform the fire authorities and the community of the bushfire hazard in an effort to manage the risk posed to life, property and the environment. - -Bushfire attack level (BAL) is a measure of the severity of a building's potential exposure to bushfire. It is defined in the Australian standard AS 3959 (2009)--Construction of buildings in bushfire-prone areas, to serve as a basis for establishing the requirements for construction, to improve the protection of buildings from bushfire attack. The Standard describes how to compute the bushfire attack level for any location and directly links this to recommendations on the design of existing or planned buildings. - -The BAL toolbox implements the rules described by method 1 in the national standard AS 3959 (2009) by integrating them into a computational code that can be run by non-technical people in an ArcGIS environment. - - -Package structures ------------------- - -The toolbox name is **BAL.tbx** that is associated with a python script **bal.py** to derive bushfire attack level values. The script **bal.py** links to a python script **calculate_bal.py** and a module **Utilities**, which includes supporting dictionaries defined in two python scripts: - -* value_lookup.py; -* bal_database.py. - -There are two more folders: - -**docs**: holding the documentation files. - -**tests**: holding the unit tests, scenario tests and their test data. \ No newline at end of file diff --git a/docs/html/_sources/docs/utilities.txt b/docs/html/_sources/docs/utilities.txt deleted file mode 100644 index d87c9bd..0000000 --- a/docs/html/_sources/docs/utilities.txt +++ /dev/null @@ -1,34 +0,0 @@ - -utilities -************ - -These are tools or functions used to support the main computation. - - -__init__.py -=========================================== - -.. automodule:: __init__ - :members: - - - -value_lookup.py -=========================================== - -.. automodule:: value_lookup - :members: - - -bal_database.py -=========================================== - -.. automodule:: bal_database - :members: - - -sa_tools.py -=========================================== - -.. automodule:: sa_tools - :members: diff --git a/docs/html/_sources/index.txt b/docs/html/_sources/index.txt deleted file mode 100644 index 0e57eb2..0000000 --- a/docs/html/_sources/index.txt +++ /dev/null @@ -1,71 +0,0 @@ -.. BAL documentation master file, created by - sphinx-quickstart on Tue Jul 14 11:29:00 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Bushfire Attack Level -=============================== - - - - -Overview -=========================================== - - -This toolbox is used to compute the Bushfire Attack Level (BAL) for an area of interest within Australia based on the input vegetation and elevation datasets. - -The computation algorithm is adapted spatially to Method 1 in the Australian Standard AS 3959 (2009)--*Construction of buildings in bushfire-prone areas*. - -The output contains eight raster files that represent the BAL for each of eight cardinal directions and an extra raster file that represents the maximum BAL of the eight directions for each grid cell. - - -Disclaimer -========== -.. toctree:: - :maxdepth: 1 - - Disclaimer - - -Introduction -============ -.. toctree:: - :maxdepth: 1 - - Introduction - Background - - -How to use the toolbox -====================== -.. toctree:: - :maxdepth: 1 - - Installation - Setting up the toolbox - Running the toolbox - Examples - - -Code documentation -================== - -This part is extracted from the source code in-line documentation and included in this document for the completeness of the software package. It does not directly instruct users how to use the toolbox to calculate the BAL. Instead, it might be useful for software engineers or developers to review the source code and maintain or upgrade it in the future. - -.. toctree:: - :maxdepth: 2 - - docs/bal - docs/calculate_bal - docs/utilities - - -References -========== - -AS 3959, 2009. Construction of buildings in bushfire-prone areas, Australian Standard - - - - diff --git a/docs/html/_static/ajax-loader.gif b/docs/html/_static/ajax-loader.gif deleted file mode 100644 index 61faf8c..0000000 Binary files a/docs/html/_static/ajax-loader.gif and /dev/null differ diff --git a/docs/html/_static/basic.css b/docs/html/_static/basic.css deleted file mode 100644 index 43e8baf..0000000 --- a/docs/html/_static/basic.css +++ /dev/null @@ -1,540 +0,0 @@ -/* - * basic.css - * ~~~~~~~~~ - * - * Sphinx stylesheet -- basic theme. - * - * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -/* -- main layout ----------------------------------------------------------- */ - -div.clearer { - clear: both; -} - -/* -- relbar ---------------------------------------------------------------- */ - -div.related { - width: 100%; - font-size: 90%; -} - -div.related h3 { - display: none; -} - -div.related ul { - margin: 0; - padding: 0 0 0 10px; - list-style: none; -} - -div.related li { - display: inline; -} - -div.related li.right { - float: right; - margin-right: 5px; -} - -/* -- sidebar --------------------------------------------------------------- */ - -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -div.sphinxsidebar { - float: left; - width: 230px; - margin-left: -100%; - font-size: 90%; -} - -div.sphinxsidebar ul { - list-style: none; -} - -div.sphinxsidebar ul ul, -div.sphinxsidebar ul.want-points { - margin-left: 20px; - list-style: square; -} - -div.sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - -div.sphinxsidebar form { - margin-top: 10px; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -div.sphinxsidebar #searchbox input[type="text"] { - width: 170px; -} - -div.sphinxsidebar #searchbox input[type="submit"] { - width: 30px; -} - -img { - border: 0; -} - -/* -- search page ----------------------------------------------------------- */ - -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -/* -- index page ------------------------------------------------------------ */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -/* -- general index --------------------------------------------------------- */ - -table.indextable { - width: 100%; -} - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -div.modindex-jumpbox { - border-top: 1px solid #ddd; - border-bottom: 1px solid #ddd; - margin: 1em 0 1em 0; - padding: 0.4em; -} - -div.genindex-jumpbox { - border-top: 1px solid #ddd; - border-bottom: 1px solid #ddd; - margin: 1em 0 1em 0; - padding: 0.4em; -} - -/* -- general body styles --------------------------------------------------- */ - -a.headerlink { - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -div.body p.caption { - text-align: inherit; -} - -div.body td { - text-align: left; -} - -.field-list ul { - padding-left: 1em; -} - -.first { - margin-top: 0 !important; -} - -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -img.align-left, .figure.align-left, object.align-left { - clear: left; - float: left; - margin-right: 1em; -} - -img.align-right, .figure.align-right, object.align-right { - clear: right; - float: right; - margin-left: 1em; -} - -img.align-center, .figure.align-center, object.align-center { - display: block; - margin-left: auto; - margin-right: auto; -} - -.align-left { - text-align: left; -} - -.align-center { - text-align: center; -} - -.align-right { - text-align: right; -} - -/* -- sidebars -------------------------------------------------------------- */ - -div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} - -p.sidebar-title { - font-weight: bold; -} - -/* -- topics ---------------------------------------------------------------- */ - -div.topic { - border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* -- admonitions ----------------------------------------------------------- */ - -div.admonition { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dl { - margin-bottom: 0; -} - -p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; -} - -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -/* -- tables ---------------------------------------------------------------- */ - -table.docutils { - border: 0; - border-collapse: collapse; -} - -table.docutils td, table.docutils th { - padding: 1px 8px 1px 5px; - border-top: 0; - border-left: 0; - border-right: 0; - border-bottom: 1px solid #aaa; -} - -table.field-list td, table.field-list th { - border: 0 !important; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -th { - text-align: left; - padding-right: 5px; -} - -table.citation { - border-left: solid 1px gray; - margin-left: 1px; -} - -table.citation td { - border-bottom: none; -} - -/* -- other body styles ----------------------------------------------------- */ - -ol.arabic { - list-style: decimal; -} - -ol.loweralpha { - list-style: lower-alpha; -} - -ol.upperalpha { - list-style: upper-alpha; -} - -ol.lowerroman { - list-style: lower-roman; -} - -ol.upperroman { - list-style: upper-roman; -} - -dl { - margin-bottom: 15px; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -dt:target, .highlighted { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -.refcount { - color: #060; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} - -.footnote:target { - background-color: #ffa; -} - -.line-block { - display: block; - margin-top: 1em; - margin-bottom: 1em; -} - -.line-block .line-block { - margin-top: 0; - margin-bottom: 0; - margin-left: 1.5em; -} - -.guilabel, .menuselection { - font-family: sans-serif; -} - -.accelerator { - text-decoration: underline; -} - -.classifier { - font-style: oblique; -} - -abbr, acronym { - border-bottom: dotted 1px; - cursor: help; -} - -/* -- code displays --------------------------------------------------------- */ - -pre { - overflow: auto; - overflow-y: hidden; /* fixes display issues on Chrome browsers */ -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -.viewcode-link { - float: right; -} - -.viewcode-back { - float: right; - font-family: sans-serif; -} - -div.viewcode-block:target { - margin: -1px -10px; - padding: 0 10px; -} - -/* -- math display ---------------------------------------------------------- */ - -img.math { - vertical-align: middle; -} - -div.body div.math p { - text-align: center; -} - -span.eqno { - float: right; -} - -/* -- printout stylesheet --------------------------------------------------- */ - -@media print { - div.document, - div.documentwrapper, - div.bodywrapper { - margin: 0 !important; - width: 100%; - } - - div.sphinxsidebar, - div.related, - div.footer, - #top-link { - display: none; - } -} \ No newline at end of file diff --git a/docs/html/_static/comment-bright.png b/docs/html/_static/comment-bright.png deleted file mode 100644 index 551517b..0000000 Binary files a/docs/html/_static/comment-bright.png and /dev/null differ diff --git a/docs/html/_static/comment-close.png b/docs/html/_static/comment-close.png deleted file mode 100644 index 09b54be..0000000 Binary files a/docs/html/_static/comment-close.png and /dev/null differ diff --git a/docs/html/_static/comment.png b/docs/html/_static/comment.png deleted file mode 100644 index 92feb52..0000000 Binary files a/docs/html/_static/comment.png and /dev/null differ diff --git a/docs/html/_static/default.css b/docs/html/_static/default.css deleted file mode 100644 index 21f3f50..0000000 --- a/docs/html/_static/default.css +++ /dev/null @@ -1,256 +0,0 @@ -/* - * default.css_t - * ~~~~~~~~~~~~~ - * - * Sphinx stylesheet -- default theme. - * - * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: sans-serif; - font-size: 100%; - background-color: #11303d; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - background-color: #1c4e63; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 230px; -} - -div.body { - background-color: #ffffff; - color: #000000; - padding: 0 20px 30px 20px; -} - -div.footer { - color: #ffffff; - width: 100%; - padding: 9px 0 9px 0; - text-align: center; - font-size: 75%; -} - -div.footer a { - color: #ffffff; - text-decoration: underline; -} - -div.related { - background-color: #133f52; - line-height: 30px; - color: #ffffff; -} - -div.related a { - color: #ffffff; -} - -div.sphinxsidebar { -} - -div.sphinxsidebar h3 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.4em; - font-weight: normal; - margin: 0; - padding: 0; -} - -div.sphinxsidebar h3 a { - color: #ffffff; -} - -div.sphinxsidebar h4 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.3em; - font-weight: normal; - margin: 5px 0 0 0; - padding: 0; -} - -div.sphinxsidebar p { - color: #ffffff; -} - -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; -} - -div.sphinxsidebar ul { - margin: 10px; - padding: 0; - color: #ffffff; -} - -div.sphinxsidebar a { - color: #98dbcc; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - - - -/* -- hyperlink styles ------------------------------------------------------ */ - -a { - color: #355f7c; - text-decoration: none; -} - -a:visited { - color: #355f7c; - text-decoration: none; -} - -a:hover { - text-decoration: underline; -} - - - -/* -- body styles ----------------------------------------------------------- */ - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Trebuchet MS', sans-serif; - background-color: #f2f2f2; - font-weight: normal; - color: #20435c; - border-bottom: 1px solid #ccc; - margin: 20px -20px 10px -20px; - padding: 3px 0 3px 10px; -} - -div.body h1 { margin-top: 0; font-size: 200%; } -div.body h2 { font-size: 160%; } -div.body h3 { font-size: 140%; } -div.body h4 { font-size: 120%; } -div.body h5 { font-size: 110%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: justify; - line-height: 130%; -} - -div.admonition p.admonition-title + p { - display: inline; -} - -div.admonition p { - margin-bottom: 5px; -} - -div.admonition pre { - margin-bottom: 5px; -} - -div.admonition ul, div.admonition ol { - margin-bottom: 5px; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre { - padding: 5px; - background-color: #eeffcc; - color: #333333; - line-height: 120%; - border: 1px solid #ac9; - border-left: none; - border-right: none; -} - -tt { - background-color: #ecf0f3; - padding: 0 1px 0 1px; - font-size: 0.95em; -} - -th { - background-color: #ede; -} - -.warning tt { - background: #efc2c2; -} - -.note tt { - background: #d6d6d6; -} - -.viewcode-back { - font-family: sans-serif; -} - -div.viewcode-block:target { - background-color: #f4debf; - border-top: 1px solid #ac9; - border-bottom: 1px solid #ac9; -} \ No newline at end of file diff --git a/docs/html/_static/doctools.js b/docs/html/_static/doctools.js deleted file mode 100644 index d4619fd..0000000 --- a/docs/html/_static/doctools.js +++ /dev/null @@ -1,247 +0,0 @@ -/* - * doctools.js - * ~~~~~~~~~~~ - * - * Sphinx JavaScript utilities for all documentation. - * - * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -/** - * select a different prefix for underscore - */ -$u = _.noConflict(); - -/** - * make the code below compatible with browsers without - * an installed firebug like debugger -if (!window.console || !console.firebug) { - var names = ["log", "debug", "info", "warn", "error", "assert", "dir", - "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", - "profile", "profileEnd"]; - window.console = {}; - for (var i = 0; i < names.length; ++i) - window.console[names[i]] = function() {}; -} - */ - -/** - * small helper function to urldecode strings - */ -jQuery.urldecode = function(x) { - return decodeURIComponent(x).replace(/\+/g, ' '); -} - -/** - * small helper function to urlencode strings - */ -jQuery.urlencode = encodeURIComponent; - -/** - * This function returns the parsed url parameters of the - * current request. Multiple values per key are supported, - * it will always return arrays of strings for the value parts. - */ -jQuery.getQueryParameters = function(s) { - if (typeof s == 'undefined') - s = document.location.search; - var parts = s.substr(s.indexOf('?') + 1).split('&'); - var result = {}; - for (var i = 0; i < parts.length; i++) { - var tmp = parts[i].split('=', 2); - var key = jQuery.urldecode(tmp[0]); - var value = jQuery.urldecode(tmp[1]); - if (key in result) - result[key].push(value); - else - result[key] = [value]; - } - return result; -}; - -/** - * small function to check if an array contains - * a given item. - */ -jQuery.contains = function(arr, item) { - for (var i = 0; i < arr.length; i++) { - if (arr[i] == item) - return true; - } - return false; -}; - -/** - * highlight a given string on a jquery object by wrapping it in - * span elements with the given class name. - */ -jQuery.fn.highlightText = function(text, className) { - function highlight(node) { - if (node.nodeType == 3) { - var val = node.nodeValue; - var pos = val.toLowerCase().indexOf(text); - if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) { - var span = document.createElement("span"); - span.className = className; - span.appendChild(document.createTextNode(val.substr(pos, text.length))); - node.parentNode.insertBefore(span, node.parentNode.insertBefore( - document.createTextNode(val.substr(pos + text.length)), - node.nextSibling)); - node.nodeValue = val.substr(0, pos); - } - } - else if (!jQuery(node).is("button, select, textarea")) { - jQuery.each(node.childNodes, function() { - highlight(this); - }); - } - } - return this.each(function() { - highlight(this); - }); -}; - -/** - * Small JavaScript module for the documentation. - */ -var Documentation = { - - init : function() { - this.fixFirefoxAnchorBug(); - this.highlightSearchWords(); - this.initIndexTable(); - }, - - /** - * i18n support - */ - TRANSLATIONS : {}, - PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, - LOCALE : 'unknown', - - // gettext and ngettext don't access this so that the functions - // can safely bound to a different name (_ = Documentation.gettext) - gettext : function(string) { - var translated = Documentation.TRANSLATIONS[string]; - if (typeof translated == 'undefined') - return string; - return (typeof translated == 'string') ? translated : translated[0]; - }, - - ngettext : function(singular, plural, n) { - var translated = Documentation.TRANSLATIONS[singular]; - if (typeof translated == 'undefined') - return (n == 1) ? singular : plural; - return translated[Documentation.PLURALEXPR(n)]; - }, - - addTranslations : function(catalog) { - for (var key in catalog.messages) - this.TRANSLATIONS[key] = catalog.messages[key]; - this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); - this.LOCALE = catalog.locale; - }, - - /** - * add context elements like header anchor links - */ - addContextElements : function() { - $('div[id] > :header:first').each(function() { - $('\u00B6'). - attr('href', '#' + this.id). - attr('title', _('Permalink to this headline')). - appendTo(this); - }); - $('dt[id]').each(function() { - $('\u00B6'). - attr('href', '#' + this.id). - attr('title', _('Permalink to this definition')). - appendTo(this); - }); - }, - - /** - * workaround a firefox stupidity - */ - fixFirefoxAnchorBug : function() { - if (document.location.hash && $.browser.mozilla) - window.setTimeout(function() { - document.location.href += ''; - }, 10); - }, - - /** - * highlight the search words provided in the url in the text - */ - highlightSearchWords : function() { - var params = $.getQueryParameters(); - var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; - if (terms.length) { - var body = $('div.body'); - window.setTimeout(function() { - $.each(terms, function() { - body.highlightText(this.toLowerCase(), 'highlighted'); - }); - }, 10); - $('

' + _('Hide Search Matches') + '

') - .appendTo($('#searchbox')); - } - }, - - /** - * init the domain index toggle buttons - */ - initIndexTable : function() { - var togglers = $('img.toggler').click(function() { - var src = $(this).attr('src'); - var idnum = $(this).attr('id').substr(7); - $('tr.cg-' + idnum).toggle(); - if (src.substr(-9) == 'minus.png') - $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); - else - $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); - }).css('display', ''); - if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { - togglers.click(); - } - }, - - /** - * helper function to hide the search marks again - */ - hideSearchWords : function() { - $('#searchbox .highlight-link').fadeOut(300); - $('span.highlighted').removeClass('highlighted'); - }, - - /** - * make the url absolute - */ - makeURL : function(relativeURL) { - return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; - }, - - /** - * get the current relative url - */ - getCurrentURL : function() { - var path = document.location.pathname; - var parts = path.split(/\//); - $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { - if (this == '..') - parts.pop(); - }); - var url = parts.join('/'); - return path.substring(url.lastIndexOf('/') + 1, path.length - 1); - } -}; - -// quick alias for translations -_ = Documentation.gettext; - -$(document).ready(function() { - Documentation.init(); -}); diff --git a/docs/html/_static/down-pressed.png b/docs/html/_static/down-pressed.png deleted file mode 100644 index 6f7ad78..0000000 Binary files a/docs/html/_static/down-pressed.png and /dev/null differ diff --git a/docs/html/_static/down.png b/docs/html/_static/down.png deleted file mode 100644 index 3003a88..0000000 Binary files a/docs/html/_static/down.png and /dev/null differ diff --git a/docs/html/_static/file.png b/docs/html/_static/file.png deleted file mode 100644 index d18082e..0000000 Binary files a/docs/html/_static/file.png and /dev/null differ diff --git a/docs/html/_static/jquery.js b/docs/html/_static/jquery.js deleted file mode 100644 index 7c24308..0000000 --- a/docs/html/_static/jquery.js +++ /dev/null @@ -1,154 +0,0 @@ -/*! - * jQuery JavaScript Library v1.4.2 - * http://jquery.com/ - * - * Copyright 2010, John Resig - * Dual licensed under the MIT or GPL Version 2 licenses. - * http://jquery.org/license - * - * Includes Sizzle.js - * http://sizzlejs.com/ - * Copyright 2010, The Dojo Foundation - * Released under the MIT, BSD, and GPL Licenses. - * - * Date: Sat Feb 13 22:33:48 2010 -0500 - */ -(function(A,w){function ma(){if(!c.isReady){try{s.documentElement.doScroll("left")}catch(a){setTimeout(ma,1);return}c.ready()}}function Qa(a,b){b.src?c.ajax({url:b.src,async:false,dataType:"script"}):c.globalEval(b.text||b.textContent||b.innerHTML||"");b.parentNode&&b.parentNode.removeChild(b)}function X(a,b,d,f,e,j){var i=a.length;if(typeof b==="object"){for(var o in b)X(a,o,b[o],f,e,d);return a}if(d!==w){f=!j&&f&&c.isFunction(d);for(o=0;o)[^>]*$|^#([\w-]+)$/,Ua=/^.[^:#\[\.,]*$/,Va=/\S/, -Wa=/^(\s|\u00A0)+|(\s|\u00A0)+$/g,Xa=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,P=navigator.userAgent,xa=false,Q=[],L,$=Object.prototype.toString,aa=Object.prototype.hasOwnProperty,ba=Array.prototype.push,R=Array.prototype.slice,ya=Array.prototype.indexOf;c.fn=c.prototype={init:function(a,b){var d,f;if(!a)return this;if(a.nodeType){this.context=this[0]=a;this.length=1;return this}if(a==="body"&&!b){this.context=s;this[0]=s.body;this.selector="body";this.length=1;return this}if(typeof a==="string")if((d=Ta.exec(a))&& -(d[1]||!b))if(d[1]){f=b?b.ownerDocument||b:s;if(a=Xa.exec(a))if(c.isPlainObject(b)){a=[s.createElement(a[1])];c.fn.attr.call(a,b,true)}else a=[f.createElement(a[1])];else{a=sa([d[1]],[f]);a=(a.cacheable?a.fragment.cloneNode(true):a.fragment).childNodes}return c.merge(this,a)}else{if(b=s.getElementById(d[2])){if(b.id!==d[2])return T.find(a);this.length=1;this[0]=b}this.context=s;this.selector=a;return this}else if(!b&&/^\w+$/.test(a)){this.selector=a;this.context=s;a=s.getElementsByTagName(a);return c.merge(this, -a)}else return!b||b.jquery?(b||T).find(a):c(b).find(a);else if(c.isFunction(a))return T.ready(a);if(a.selector!==w){this.selector=a.selector;this.context=a.context}return c.makeArray(a,this)},selector:"",jquery:"1.4.2",length:0,size:function(){return this.length},toArray:function(){return R.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this.slice(a)[0]:this[a]},pushStack:function(a,b,d){var f=c();c.isArray(a)?ba.apply(f,a):c.merge(f,a);f.prevObject=this;f.context=this.context;if(b=== -"find")f.selector=this.selector+(this.selector?" ":"")+d;else if(b)f.selector=this.selector+"."+b+"("+d+")";return f},each:function(a,b){return c.each(this,a,b)},ready:function(a){c.bindReady();if(c.isReady)a.call(s,c);else Q&&Q.push(a);return this},eq:function(a){return a===-1?this.slice(a):this.slice(a,+a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(R.apply(this,arguments),"slice",R.call(arguments).join(","))},map:function(a){return this.pushStack(c.map(this, -function(b,d){return a.call(b,d,b)}))},end:function(){return this.prevObject||c(null)},push:ba,sort:[].sort,splice:[].splice};c.fn.init.prototype=c.fn;c.extend=c.fn.extend=function(){var a=arguments[0]||{},b=1,d=arguments.length,f=false,e,j,i,o;if(typeof a==="boolean"){f=a;a=arguments[1]||{};b=2}if(typeof a!=="object"&&!c.isFunction(a))a={};if(d===b){a=this;--b}for(;b
a"; -var e=d.getElementsByTagName("*"),j=d.getElementsByTagName("a")[0];if(!(!e||!e.length||!j)){c.support={leadingWhitespace:d.firstChild.nodeType===3,tbody:!d.getElementsByTagName("tbody").length,htmlSerialize:!!d.getElementsByTagName("link").length,style:/red/.test(j.getAttribute("style")),hrefNormalized:j.getAttribute("href")==="/a",opacity:/^0.55$/.test(j.style.opacity),cssFloat:!!j.style.cssFloat,checkOn:d.getElementsByTagName("input")[0].value==="on",optSelected:s.createElement("select").appendChild(s.createElement("option")).selected, -parentNode:d.removeChild(d.appendChild(s.createElement("div"))).parentNode===null,deleteExpando:true,checkClone:false,scriptEval:false,noCloneEvent:true,boxModel:null};b.type="text/javascript";try{b.appendChild(s.createTextNode("window."+f+"=1;"))}catch(i){}a.insertBefore(b,a.firstChild);if(A[f]){c.support.scriptEval=true;delete A[f]}try{delete b.test}catch(o){c.support.deleteExpando=false}a.removeChild(b);if(d.attachEvent&&d.fireEvent){d.attachEvent("onclick",function k(){c.support.noCloneEvent= -false;d.detachEvent("onclick",k)});d.cloneNode(true).fireEvent("onclick")}d=s.createElement("div");d.innerHTML="";a=s.createDocumentFragment();a.appendChild(d.firstChild);c.support.checkClone=a.cloneNode(true).cloneNode(true).lastChild.checked;c(function(){var k=s.createElement("div");k.style.width=k.style.paddingLeft="1px";s.body.appendChild(k);c.boxModel=c.support.boxModel=k.offsetWidth===2;s.body.removeChild(k).style.display="none"});a=function(k){var n= -s.createElement("div");k="on"+k;var r=k in n;if(!r){n.setAttribute(k,"return;");r=typeof n[k]==="function"}return r};c.support.submitBubbles=a("submit");c.support.changeBubbles=a("change");a=b=d=e=j=null}})();c.props={"for":"htmlFor","class":"className",readonly:"readOnly",maxlength:"maxLength",cellspacing:"cellSpacing",rowspan:"rowSpan",colspan:"colSpan",tabindex:"tabIndex",usemap:"useMap",frameborder:"frameBorder"};var G="jQuery"+J(),Ya=0,za={};c.extend({cache:{},expando:G,noData:{embed:true,object:true, -applet:true},data:function(a,b,d){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var f=a[G],e=c.cache;if(!f&&typeof b==="string"&&d===w)return null;f||(f=++Ya);if(typeof b==="object"){a[G]=f;e[f]=c.extend(true,{},b)}else if(!e[f]){a[G]=f;e[f]={}}a=e[f];if(d!==w)a[b]=d;return typeof b==="string"?a[b]:a}},removeData:function(a,b){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var d=a[G],f=c.cache,e=f[d];if(b){if(e){delete e[b];c.isEmptyObject(e)&&c.removeData(a)}}else{if(c.support.deleteExpando)delete a[c.expando]; -else a.removeAttribute&&a.removeAttribute(c.expando);delete f[d]}}}});c.fn.extend({data:function(a,b){if(typeof a==="undefined"&&this.length)return c.data(this[0]);else if(typeof a==="object")return this.each(function(){c.data(this,a)});var d=a.split(".");d[1]=d[1]?"."+d[1]:"";if(b===w){var f=this.triggerHandler("getData"+d[1]+"!",[d[0]]);if(f===w&&this.length)f=c.data(this[0],a);return f===w&&d[1]?this.data(d[0]):f}else return this.trigger("setData"+d[1]+"!",[d[0],b]).each(function(){c.data(this, -a,b)})},removeData:function(a){return this.each(function(){c.removeData(this,a)})}});c.extend({queue:function(a,b,d){if(a){b=(b||"fx")+"queue";var f=c.data(a,b);if(!d)return f||[];if(!f||c.isArray(d))f=c.data(a,b,c.makeArray(d));else f.push(d);return f}},dequeue:function(a,b){b=b||"fx";var d=c.queue(a,b),f=d.shift();if(f==="inprogress")f=d.shift();if(f){b==="fx"&&d.unshift("inprogress");f.call(a,function(){c.dequeue(a,b)})}}});c.fn.extend({queue:function(a,b){if(typeof a!=="string"){b=a;a="fx"}if(b=== -w)return c.queue(this[0],a);return this.each(function(){var d=c.queue(this,a,b);a==="fx"&&d[0]!=="inprogress"&&c.dequeue(this,a)})},dequeue:function(a){return this.each(function(){c.dequeue(this,a)})},delay:function(a,b){a=c.fx?c.fx.speeds[a]||a:a;b=b||"fx";return this.queue(b,function(){var d=this;setTimeout(function(){c.dequeue(d,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])}});var Aa=/[\n\t]/g,ca=/\s+/,Za=/\r/g,$a=/href|src|style/,ab=/(button|input)/i,bb=/(button|input|object|select|textarea)/i, -cb=/^(a|area)$/i,Ba=/radio|checkbox/;c.fn.extend({attr:function(a,b){return X(this,a,b,true,c.attr)},removeAttr:function(a){return this.each(function(){c.attr(this,a,"");this.nodeType===1&&this.removeAttribute(a)})},addClass:function(a){if(c.isFunction(a))return this.each(function(n){var r=c(this);r.addClass(a.call(this,n,r.attr("class")))});if(a&&typeof a==="string")for(var b=(a||"").split(ca),d=0,f=this.length;d-1)return true;return false},val:function(a){if(a===w){var b=this[0];if(b){if(c.nodeName(b,"option"))return(b.attributes.value||{}).specified?b.value:b.text;if(c.nodeName(b,"select")){var d=b.selectedIndex,f=[],e=b.options;b=b.type==="select-one";if(d<0)return null;var j=b?d:0;for(d=b?d+1:e.length;j=0;else if(c.nodeName(this,"select")){var u=c.makeArray(r);c("option",this).each(function(){this.selected= -c.inArray(c(this).val(),u)>=0});if(!u.length)this.selectedIndex=-1}else this.value=r}})}});c.extend({attrFn:{val:true,css:true,html:true,text:true,data:true,width:true,height:true,offset:true},attr:function(a,b,d,f){if(!a||a.nodeType===3||a.nodeType===8)return w;if(f&&b in c.attrFn)return c(a)[b](d);f=a.nodeType!==1||!c.isXMLDoc(a);var e=d!==w;b=f&&c.props[b]||b;if(a.nodeType===1){var j=$a.test(b);if(b in a&&f&&!j){if(e){b==="type"&&ab.test(a.nodeName)&&a.parentNode&&c.error("type property can't be changed"); -a[b]=d}if(c.nodeName(a,"form")&&a.getAttributeNode(b))return a.getAttributeNode(b).nodeValue;if(b==="tabIndex")return(b=a.getAttributeNode("tabIndex"))&&b.specified?b.value:bb.test(a.nodeName)||cb.test(a.nodeName)&&a.href?0:w;return a[b]}if(!c.support.style&&f&&b==="style"){if(e)a.style.cssText=""+d;return a.style.cssText}e&&a.setAttribute(b,""+d);a=!c.support.hrefNormalized&&f&&j?a.getAttribute(b,2):a.getAttribute(b);return a===null?w:a}return c.style(a,b,d)}});var O=/\.(.*)$/,db=function(a){return a.replace(/[^\w\s\.\|`]/g, -function(b){return"\\"+b})};c.event={add:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){if(a.setInterval&&a!==A&&!a.frameElement)a=A;var e,j;if(d.handler){e=d;d=e.handler}if(!d.guid)d.guid=c.guid++;if(j=c.data(a)){var i=j.events=j.events||{},o=j.handle;if(!o)j.handle=o=function(){return typeof c!=="undefined"&&!c.event.triggered?c.event.handle.apply(o.elem,arguments):w};o.elem=a;b=b.split(" ");for(var k,n=0,r;k=b[n++];){j=e?c.extend({},e):{handler:d,data:f};if(k.indexOf(".")>-1){r=k.split("."); -k=r.shift();j.namespace=r.slice(0).sort().join(".")}else{r=[];j.namespace=""}j.type=k;j.guid=d.guid;var u=i[k],z=c.event.special[k]||{};if(!u){u=i[k]=[];if(!z.setup||z.setup.call(a,f,r,o)===false)if(a.addEventListener)a.addEventListener(k,o,false);else a.attachEvent&&a.attachEvent("on"+k,o)}if(z.add){z.add.call(a,j);if(!j.handler.guid)j.handler.guid=d.guid}u.push(j);c.event.global[k]=true}a=null}}},global:{},remove:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){var e,j=0,i,o,k,n,r,u,z=c.data(a), -C=z&&z.events;if(z&&C){if(b&&b.type){d=b.handler;b=b.type}if(!b||typeof b==="string"&&b.charAt(0)==="."){b=b||"";for(e in C)c.event.remove(a,e+b)}else{for(b=b.split(" ");e=b[j++];){n=e;i=e.indexOf(".")<0;o=[];if(!i){o=e.split(".");e=o.shift();k=new RegExp("(^|\\.)"+c.map(o.slice(0).sort(),db).join("\\.(?:.*\\.)?")+"(\\.|$)")}if(r=C[e])if(d){n=c.event.special[e]||{};for(B=f||0;B=0){a.type= -e=e.slice(0,-1);a.exclusive=true}if(!d){a.stopPropagation();c.event.global[e]&&c.each(c.cache,function(){this.events&&this.events[e]&&c.event.trigger(a,b,this.handle.elem)})}if(!d||d.nodeType===3||d.nodeType===8)return w;a.result=w;a.target=d;b=c.makeArray(b);b.unshift(a)}a.currentTarget=d;(f=c.data(d,"handle"))&&f.apply(d,b);f=d.parentNode||d.ownerDocument;try{if(!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()]))if(d["on"+e]&&d["on"+e].apply(d,b)===false)a.result=false}catch(j){}if(!a.isPropagationStopped()&& -f)c.event.trigger(a,b,f,true);else if(!a.isDefaultPrevented()){f=a.target;var i,o=c.nodeName(f,"a")&&e==="click",k=c.event.special[e]||{};if((!k._default||k._default.call(d,a)===false)&&!o&&!(f&&f.nodeName&&c.noData[f.nodeName.toLowerCase()])){try{if(f[e]){if(i=f["on"+e])f["on"+e]=null;c.event.triggered=true;f[e]()}}catch(n){}if(i)f["on"+e]=i;c.event.triggered=false}}},handle:function(a){var b,d,f,e;a=arguments[0]=c.event.fix(a||A.event);a.currentTarget=this;b=a.type.indexOf(".")<0&&!a.exclusive; -if(!b){d=a.type.split(".");a.type=d.shift();f=new RegExp("(^|\\.)"+d.slice(0).sort().join("\\.(?:.*\\.)?")+"(\\.|$)")}e=c.data(this,"events");d=e[a.type];if(e&&d){d=d.slice(0);e=0;for(var j=d.length;e-1?c.map(a.options,function(f){return f.selected}).join("-"):"";else if(a.nodeName.toLowerCase()==="select")d=a.selectedIndex;return d},fa=function(a,b){var d=a.target,f,e;if(!(!da.test(d.nodeName)||d.readOnly)){f=c.data(d,"_change_data");e=Fa(d);if(a.type!=="focusout"||d.type!=="radio")c.data(d,"_change_data", -e);if(!(f===w||e===f))if(f!=null||e){a.type="change";return c.event.trigger(a,b,d)}}};c.event.special.change={filters:{focusout:fa,click:function(a){var b=a.target,d=b.type;if(d==="radio"||d==="checkbox"||b.nodeName.toLowerCase()==="select")return fa.call(this,a)},keydown:function(a){var b=a.target,d=b.type;if(a.keyCode===13&&b.nodeName.toLowerCase()!=="textarea"||a.keyCode===32&&(d==="checkbox"||d==="radio")||d==="select-multiple")return fa.call(this,a)},beforeactivate:function(a){a=a.target;c.data(a, -"_change_data",Fa(a))}},setup:function(){if(this.type==="file")return false;for(var a in ea)c.event.add(this,a+".specialChange",ea[a]);return da.test(this.nodeName)},teardown:function(){c.event.remove(this,".specialChange");return da.test(this.nodeName)}};ea=c.event.special.change.filters}s.addEventListener&&c.each({focus:"focusin",blur:"focusout"},function(a,b){function d(f){f=c.event.fix(f);f.type=b;return c.event.handle.call(this,f)}c.event.special[b]={setup:function(){this.addEventListener(a, -d,true)},teardown:function(){this.removeEventListener(a,d,true)}}});c.each(["bind","one"],function(a,b){c.fn[b]=function(d,f,e){if(typeof d==="object"){for(var j in d)this[b](j,f,d[j],e);return this}if(c.isFunction(f)){e=f;f=w}var i=b==="one"?c.proxy(e,function(k){c(this).unbind(k,i);return e.apply(this,arguments)}):e;if(d==="unload"&&b!=="one")this.one(d,f,e);else{j=0;for(var o=this.length;j0){y=t;break}}t=t[g]}m[q]=y}}}var f=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^[\]]*\]|['"][^'"]*['"]|[^[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g, -e=0,j=Object.prototype.toString,i=false,o=true;[0,0].sort(function(){o=false;return 0});var k=function(g,h,l,m){l=l||[];var q=h=h||s;if(h.nodeType!==1&&h.nodeType!==9)return[];if(!g||typeof g!=="string")return l;for(var p=[],v,t,y,S,H=true,M=x(h),I=g;(f.exec(""),v=f.exec(I))!==null;){I=v[3];p.push(v[1]);if(v[2]){S=v[3];break}}if(p.length>1&&r.exec(g))if(p.length===2&&n.relative[p[0]])t=ga(p[0]+p[1],h);else for(t=n.relative[p[0]]?[h]:k(p.shift(),h);p.length;){g=p.shift();if(n.relative[g])g+=p.shift(); -t=ga(g,t)}else{if(!m&&p.length>1&&h.nodeType===9&&!M&&n.match.ID.test(p[0])&&!n.match.ID.test(p[p.length-1])){v=k.find(p.shift(),h,M);h=v.expr?k.filter(v.expr,v.set)[0]:v.set[0]}if(h){v=m?{expr:p.pop(),set:z(m)}:k.find(p.pop(),p.length===1&&(p[0]==="~"||p[0]==="+")&&h.parentNode?h.parentNode:h,M);t=v.expr?k.filter(v.expr,v.set):v.set;if(p.length>0)y=z(t);else H=false;for(;p.length;){var D=p.pop();v=D;if(n.relative[D])v=p.pop();else D="";if(v==null)v=h;n.relative[D](y,v,M)}}else y=[]}y||(y=t);y||k.error(D|| -g);if(j.call(y)==="[object Array]")if(H)if(h&&h.nodeType===1)for(g=0;y[g]!=null;g++){if(y[g]&&(y[g]===true||y[g].nodeType===1&&E(h,y[g])))l.push(t[g])}else for(g=0;y[g]!=null;g++)y[g]&&y[g].nodeType===1&&l.push(t[g]);else l.push.apply(l,y);else z(y,l);if(S){k(S,q,l,m);k.uniqueSort(l)}return l};k.uniqueSort=function(g){if(B){i=o;g.sort(B);if(i)for(var h=1;h":function(g,h){var l=typeof h==="string";if(l&&!/\W/.test(h)){h=h.toLowerCase();for(var m=0,q=g.length;m=0))l||m.push(v);else if(l)h[p]=false;return false},ID:function(g){return g[1].replace(/\\/g,"")},TAG:function(g){return g[1].toLowerCase()}, -CHILD:function(g){if(g[1]==="nth"){var h=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(g[2]==="even"&&"2n"||g[2]==="odd"&&"2n+1"||!/\D/.test(g[2])&&"0n+"+g[2]||g[2]);g[2]=h[1]+(h[2]||1)-0;g[3]=h[3]-0}g[0]=e++;return g},ATTR:function(g,h,l,m,q,p){h=g[1].replace(/\\/g,"");if(!p&&n.attrMap[h])g[1]=n.attrMap[h];if(g[2]==="~=")g[4]=" "+g[4]+" ";return g},PSEUDO:function(g,h,l,m,q){if(g[1]==="not")if((f.exec(g[3])||"").length>1||/^\w/.test(g[3]))g[3]=k(g[3],null,null,h);else{g=k.filter(g[3],h,l,true^q);l||m.push.apply(m, -g);return false}else if(n.match.POS.test(g[0])||n.match.CHILD.test(g[0]))return true;return g},POS:function(g){g.unshift(true);return g}},filters:{enabled:function(g){return g.disabled===false&&g.type!=="hidden"},disabled:function(g){return g.disabled===true},checked:function(g){return g.checked===true},selected:function(g){return g.selected===true},parent:function(g){return!!g.firstChild},empty:function(g){return!g.firstChild},has:function(g,h,l){return!!k(l[3],g).length},header:function(g){return/h\d/i.test(g.nodeName)}, -text:function(g){return"text"===g.type},radio:function(g){return"radio"===g.type},checkbox:function(g){return"checkbox"===g.type},file:function(g){return"file"===g.type},password:function(g){return"password"===g.type},submit:function(g){return"submit"===g.type},image:function(g){return"image"===g.type},reset:function(g){return"reset"===g.type},button:function(g){return"button"===g.type||g.nodeName.toLowerCase()==="button"},input:function(g){return/input|select|textarea|button/i.test(g.nodeName)}}, -setFilters:{first:function(g,h){return h===0},last:function(g,h,l,m){return h===m.length-1},even:function(g,h){return h%2===0},odd:function(g,h){return h%2===1},lt:function(g,h,l){return hl[3]-0},nth:function(g,h,l){return l[3]-0===h},eq:function(g,h,l){return l[3]-0===h}},filter:{PSEUDO:function(g,h,l,m){var q=h[1],p=n.filters[q];if(p)return p(g,l,h,m);else if(q==="contains")return(g.textContent||g.innerText||a([g])||"").indexOf(h[3])>=0;else if(q==="not"){h= -h[3];l=0;for(m=h.length;l=0}},ID:function(g,h){return g.nodeType===1&&g.getAttribute("id")===h},TAG:function(g,h){return h==="*"&&g.nodeType===1||g.nodeName.toLowerCase()===h},CLASS:function(g,h){return(" "+(g.className||g.getAttribute("class"))+" ").indexOf(h)>-1},ATTR:function(g,h){var l=h[1];g=n.attrHandle[l]?n.attrHandle[l](g):g[l]!=null?g[l]:g.getAttribute(l);l=g+"";var m=h[2];h=h[4];return g==null?m==="!=":m=== -"="?l===h:m==="*="?l.indexOf(h)>=0:m==="~="?(" "+l+" ").indexOf(h)>=0:!h?l&&g!==false:m==="!="?l!==h:m==="^="?l.indexOf(h)===0:m==="$="?l.substr(l.length-h.length)===h:m==="|="?l===h||l.substr(0,h.length+1)===h+"-":false},POS:function(g,h,l,m){var q=n.setFilters[h[2]];if(q)return q(g,l,h,m)}}},r=n.match.POS;for(var u in n.match){n.match[u]=new RegExp(n.match[u].source+/(?![^\[]*\])(?![^\(]*\))/.source);n.leftMatch[u]=new RegExp(/(^(?:.|\r|\n)*?)/.source+n.match[u].source.replace(/\\(\d+)/g,function(g, -h){return"\\"+(h-0+1)}))}var z=function(g,h){g=Array.prototype.slice.call(g,0);if(h){h.push.apply(h,g);return h}return g};try{Array.prototype.slice.call(s.documentElement.childNodes,0)}catch(C){z=function(g,h){h=h||[];if(j.call(g)==="[object Array]")Array.prototype.push.apply(h,g);else if(typeof g.length==="number")for(var l=0,m=g.length;l";var l=s.documentElement;l.insertBefore(g,l.firstChild);if(s.getElementById(h)){n.find.ID=function(m,q,p){if(typeof q.getElementById!=="undefined"&&!p)return(q=q.getElementById(m[1]))?q.id===m[1]||typeof q.getAttributeNode!=="undefined"&& -q.getAttributeNode("id").nodeValue===m[1]?[q]:w:[]};n.filter.ID=function(m,q){var p=typeof m.getAttributeNode!=="undefined"&&m.getAttributeNode("id");return m.nodeType===1&&p&&p.nodeValue===q}}l.removeChild(g);l=g=null})();(function(){var g=s.createElement("div");g.appendChild(s.createComment(""));if(g.getElementsByTagName("*").length>0)n.find.TAG=function(h,l){l=l.getElementsByTagName(h[1]);if(h[1]==="*"){h=[];for(var m=0;l[m];m++)l[m].nodeType===1&&h.push(l[m]);l=h}return l};g.innerHTML=""; -if(g.firstChild&&typeof g.firstChild.getAttribute!=="undefined"&&g.firstChild.getAttribute("href")!=="#")n.attrHandle.href=function(h){return h.getAttribute("href",2)};g=null})();s.querySelectorAll&&function(){var g=k,h=s.createElement("div");h.innerHTML="

";if(!(h.querySelectorAll&&h.querySelectorAll(".TEST").length===0)){k=function(m,q,p,v){q=q||s;if(!v&&q.nodeType===9&&!x(q))try{return z(q.querySelectorAll(m),p)}catch(t){}return g(m,q,p,v)};for(var l in g)k[l]=g[l];h=null}}(); -(function(){var g=s.createElement("div");g.innerHTML="
";if(!(!g.getElementsByClassName||g.getElementsByClassName("e").length===0)){g.lastChild.className="e";if(g.getElementsByClassName("e").length!==1){n.order.splice(1,0,"CLASS");n.find.CLASS=function(h,l,m){if(typeof l.getElementsByClassName!=="undefined"&&!m)return l.getElementsByClassName(h[1])};g=null}}})();var E=s.compareDocumentPosition?function(g,h){return!!(g.compareDocumentPosition(h)&16)}: -function(g,h){return g!==h&&(g.contains?g.contains(h):true)},x=function(g){return(g=(g?g.ownerDocument||g:0).documentElement)?g.nodeName!=="HTML":false},ga=function(g,h){var l=[],m="",q;for(h=h.nodeType?[h]:h;q=n.match.PSEUDO.exec(g);){m+=q[0];g=g.replace(n.match.PSEUDO,"")}g=n.relative[g]?g+"*":g;q=0;for(var p=h.length;q=0===d})};c.fn.extend({find:function(a){for(var b=this.pushStack("","find",a),d=0,f=0,e=this.length;f0)for(var j=d;j0},closest:function(a,b){if(c.isArray(a)){var d=[],f=this[0],e,j= -{},i;if(f&&a.length){e=0;for(var o=a.length;e-1:c(f).is(e)){d.push({selector:i,elem:f});delete j[i]}}f=f.parentNode}}return d}var k=c.expr.match.POS.test(a)?c(a,b||this.context):null;return this.map(function(n,r){for(;r&&r.ownerDocument&&r!==b;){if(k?k.index(r)>-1:c(r).is(a))return r;r=r.parentNode}return null})},index:function(a){if(!a||typeof a=== -"string")return c.inArray(this[0],a?c(a):this.parent().children());return c.inArray(a.jquery?a[0]:a,this)},add:function(a,b){a=typeof a==="string"?c(a,b||this.context):c.makeArray(a);b=c.merge(this.get(),a);return this.pushStack(qa(a[0])||qa(b[0])?b:c.unique(b))},andSelf:function(){return this.add(this.prevObject)}});c.each({parent:function(a){return(a=a.parentNode)&&a.nodeType!==11?a:null},parents:function(a){return c.dir(a,"parentNode")},parentsUntil:function(a,b,d){return c.dir(a,"parentNode", -d)},next:function(a){return c.nth(a,2,"nextSibling")},prev:function(a){return c.nth(a,2,"previousSibling")},nextAll:function(a){return c.dir(a,"nextSibling")},prevAll:function(a){return c.dir(a,"previousSibling")},nextUntil:function(a,b,d){return c.dir(a,"nextSibling",d)},prevUntil:function(a,b,d){return c.dir(a,"previousSibling",d)},siblings:function(a){return c.sibling(a.parentNode.firstChild,a)},children:function(a){return c.sibling(a.firstChild)},contents:function(a){return c.nodeName(a,"iframe")? -a.contentDocument||a.contentWindow.document:c.makeArray(a.childNodes)}},function(a,b){c.fn[a]=function(d,f){var e=c.map(this,b,d);eb.test(a)||(f=d);if(f&&typeof f==="string")e=c.filter(f,e);e=this.length>1?c.unique(e):e;if((this.length>1||gb.test(f))&&fb.test(a))e=e.reverse();return this.pushStack(e,a,R.call(arguments).join(","))}});c.extend({filter:function(a,b,d){if(d)a=":not("+a+")";return c.find.matches(a,b)},dir:function(a,b,d){var f=[];for(a=a[b];a&&a.nodeType!==9&&(d===w||a.nodeType!==1||!c(a).is(d));){a.nodeType=== -1&&f.push(a);a=a[b]}return f},nth:function(a,b,d){b=b||1;for(var f=0;a;a=a[d])if(a.nodeType===1&&++f===b)break;return a},sibling:function(a,b){for(var d=[];a;a=a.nextSibling)a.nodeType===1&&a!==b&&d.push(a);return d}});var Ja=/ jQuery\d+="(?:\d+|null)"/g,V=/^\s+/,Ka=/(<([\w:]+)[^>]*?)\/>/g,hb=/^(?:area|br|col|embed|hr|img|input|link|meta|param)$/i,La=/<([\w:]+)/,ib=/"},F={option:[1,""],legend:[1,"
","
"],thead:[1,"","
"],tr:[2,"","
"],td:[3,"","
"],col:[2,"","
"],area:[1,"",""],_default:[0,"",""]};F.optgroup=F.option;F.tbody=F.tfoot=F.colgroup=F.caption=F.thead;F.th=F.td;if(!c.support.htmlSerialize)F._default=[1,"div
","
"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d= -c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==w)return this.empty().append((this[0]&&this[0].ownerDocument||s).createTextNode(a));return c.text(this)},wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this,d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this}, -wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length?d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})}, -prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a=c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b, -this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},remove:function(a,b){for(var d=0,f;(f=this[d])!=null;d++)if(!a||c.filter(a,[f]).length){if(!b&&f.nodeType===1){c.cleanData(f.getElementsByTagName("*"));c.cleanData([f])}f.parentNode&&f.parentNode.removeChild(f)}return this},empty:function(){for(var a=0,b;(b=this[a])!=null;a++)for(b.nodeType===1&&c.cleanData(b.getElementsByTagName("*"));b.firstChild;)b.removeChild(b.firstChild); -return this},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&&!c.isXMLDoc(this)){var d=this.outerHTML,f=this.ownerDocument;if(!d){d=f.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(Ja,"").replace(/=([^="'>\s]+\/)>/g,'="$1">').replace(V,"")],f)[0]}else return this.cloneNode(true)});if(a===true){ra(this,b);ra(this.find("*"),b.find("*"))}return b},html:function(a){if(a===w)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(Ja, -""):null;else if(typeof a==="string"&&!ta.test(a)&&(c.support.leadingWhitespace||!V.test(a))&&!F[(La.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Ka,Ma);try{for(var b=0,d=this.length;b0||e.cacheable||this.length>1?k.cloneNode(true):k)}o.length&&c.each(o,Qa)}return this}});c.fragments={};c.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){c.fn[a]=function(d){var f=[];d=c(d);var e=this.length===1&&this[0].parentNode;if(e&&e.nodeType===11&&e.childNodes.length===1&&d.length===1){d[b](this[0]); -return this}else{e=0;for(var j=d.length;e0?this.clone(true):this).get();c.fn[b].apply(c(d[e]),i);f=f.concat(i)}return this.pushStack(f,a,d.selector)}}});c.extend({clean:function(a,b,d,f){b=b||s;if(typeof b.createElement==="undefined")b=b.ownerDocument||b[0]&&b[0].ownerDocument||s;for(var e=[],j=0,i;(i=a[j])!=null;j++){if(typeof i==="number")i+="";if(i){if(typeof i==="string"&&!jb.test(i))i=b.createTextNode(i);else if(typeof i==="string"){i=i.replace(Ka,Ma);var o=(La.exec(i)||["", -""])[1].toLowerCase(),k=F[o]||F._default,n=k[0],r=b.createElement("div");for(r.innerHTML=k[1]+i+k[2];n--;)r=r.lastChild;if(!c.support.tbody){n=ib.test(i);o=o==="table"&&!n?r.firstChild&&r.firstChild.childNodes:k[1]===""&&!n?r.childNodes:[];for(k=o.length-1;k>=0;--k)c.nodeName(o[k],"tbody")&&!o[k].childNodes.length&&o[k].parentNode.removeChild(o[k])}!c.support.leadingWhitespace&&V.test(i)&&r.insertBefore(b.createTextNode(V.exec(i)[0]),r.firstChild);i=r.childNodes}if(i.nodeType)e.push(i);else e= -c.merge(e,i)}}if(d)for(j=0;e[j];j++)if(f&&c.nodeName(e[j],"script")&&(!e[j].type||e[j].type.toLowerCase()==="text/javascript"))f.push(e[j].parentNode?e[j].parentNode.removeChild(e[j]):e[j]);else{e[j].nodeType===1&&e.splice.apply(e,[j+1,0].concat(c.makeArray(e[j].getElementsByTagName("script"))));d.appendChild(e[j])}return e},cleanData:function(a){for(var b,d,f=c.cache,e=c.event.special,j=c.support.deleteExpando,i=0,o;(o=a[i])!=null;i++)if(d=o[c.expando]){b=f[d];if(b.events)for(var k in b.events)e[k]? -c.event.remove(o,k):Ca(o,k,b.handle);if(j)delete o[c.expando];else o.removeAttribute&&o.removeAttribute(c.expando);delete f[d]}}});var kb=/z-?index|font-?weight|opacity|zoom|line-?height/i,Na=/alpha\([^)]*\)/,Oa=/opacity=([^)]*)/,ha=/float/i,ia=/-([a-z])/ig,lb=/([A-Z])/g,mb=/^-?\d+(?:px)?$/i,nb=/^-?\d/,ob={position:"absolute",visibility:"hidden",display:"block"},pb=["Left","Right"],qb=["Top","Bottom"],rb=s.defaultView&&s.defaultView.getComputedStyle,Pa=c.support.cssFloat?"cssFloat":"styleFloat",ja= -function(a,b){return b.toUpperCase()};c.fn.css=function(a,b){return X(this,a,b,true,function(d,f,e){if(e===w)return c.curCSS(d,f);if(typeof e==="number"&&!kb.test(f))e+="px";c.style(d,f,e)})};c.extend({style:function(a,b,d){if(!a||a.nodeType===3||a.nodeType===8)return w;if((b==="width"||b==="height")&&parseFloat(d)<0)d=w;var f=a.style||a,e=d!==w;if(!c.support.opacity&&b==="opacity"){if(e){f.zoom=1;b=parseInt(d,10)+""==="NaN"?"":"alpha(opacity="+d*100+")";a=f.filter||c.curCSS(a,"filter")||"";f.filter= -Na.test(a)?a.replace(Na,b):b}return f.filter&&f.filter.indexOf("opacity=")>=0?parseFloat(Oa.exec(f.filter)[1])/100+"":""}if(ha.test(b))b=Pa;b=b.replace(ia,ja);if(e)f[b]=d;return f[b]},css:function(a,b,d,f){if(b==="width"||b==="height"){var e,j=b==="width"?pb:qb;function i(){e=b==="width"?a.offsetWidth:a.offsetHeight;f!=="border"&&c.each(j,function(){f||(e-=parseFloat(c.curCSS(a,"padding"+this,true))||0);if(f==="margin")e+=parseFloat(c.curCSS(a,"margin"+this,true))||0;else e-=parseFloat(c.curCSS(a, -"border"+this+"Width",true))||0})}a.offsetWidth!==0?i():c.swap(a,ob,i);return Math.max(0,Math.round(e))}return c.curCSS(a,b,d)},curCSS:function(a,b,d){var f,e=a.style;if(!c.support.opacity&&b==="opacity"&&a.currentStyle){f=Oa.test(a.currentStyle.filter||"")?parseFloat(RegExp.$1)/100+"":"";return f===""?"1":f}if(ha.test(b))b=Pa;if(!d&&e&&e[b])f=e[b];else if(rb){if(ha.test(b))b="float";b=b.replace(lb,"-$1").toLowerCase();e=a.ownerDocument.defaultView;if(!e)return null;if(a=e.getComputedStyle(a,null))f= -a.getPropertyValue(b);if(b==="opacity"&&f==="")f="1"}else if(a.currentStyle){d=b.replace(ia,ja);f=a.currentStyle[b]||a.currentStyle[d];if(!mb.test(f)&&nb.test(f)){b=e.left;var j=a.runtimeStyle.left;a.runtimeStyle.left=a.currentStyle.left;e.left=d==="fontSize"?"1em":f||0;f=e.pixelLeft+"px";e.left=b;a.runtimeStyle.left=j}}return f},swap:function(a,b,d){var f={};for(var e in b){f[e]=a.style[e];a.style[e]=b[e]}d.call(a);for(e in b)a.style[e]=f[e]}});if(c.expr&&c.expr.filters){c.expr.filters.hidden=function(a){var b= -a.offsetWidth,d=a.offsetHeight,f=a.nodeName.toLowerCase()==="tr";return b===0&&d===0&&!f?true:b>0&&d>0&&!f?false:c.curCSS(a,"display")==="none"};c.expr.filters.visible=function(a){return!c.expr.filters.hidden(a)}}var sb=J(),tb=//gi,ub=/select|textarea/i,vb=/color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week/i,N=/=\?(&|$)/,ka=/\?/,wb=/(\?|&)_=.*?(&|$)/,xb=/^(\w+:)?\/\/([^\/?#]+)/,yb=/%20/g,zb=c.fn.load;c.fn.extend({load:function(a,b,d){if(typeof a!== -"string")return zb.call(this,a);else if(!this.length)return this;var f=a.indexOf(" ");if(f>=0){var e=a.slice(f,a.length);a=a.slice(0,f)}f="GET";if(b)if(c.isFunction(b)){d=b;b=null}else if(typeof b==="object"){b=c.param(b,c.ajaxSettings.traditional);f="POST"}var j=this;c.ajax({url:a,type:f,dataType:"html",data:b,complete:function(i,o){if(o==="success"||o==="notmodified")j.html(e?c("
").append(i.responseText.replace(tb,"")).find(e):i.responseText);d&&j.each(d,[i.responseText,o,i])}});return this}, -serialize:function(){return c.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?c.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||ub.test(this.nodeName)||vb.test(this.type))}).map(function(a,b){a=c(this).val();return a==null?null:c.isArray(a)?c.map(a,function(d){return{name:b.name,value:d}}):{name:b.name,value:a}}).get()}});c.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "), -function(a,b){c.fn[b]=function(d){return this.bind(b,d)}});c.extend({get:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b=null}return c.ajax({type:"GET",url:a,data:b,success:d,dataType:f})},getScript:function(a,b){return c.get(a,null,b,"script")},getJSON:function(a,b,d){return c.get(a,b,d,"json")},post:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b={}}return c.ajax({type:"POST",url:a,data:b,success:d,dataType:f})},ajaxSetup:function(a){c.extend(c.ajaxSettings,a)},ajaxSettings:{url:location.href, -global:true,type:"GET",contentType:"application/x-www-form-urlencoded",processData:true,async:true,xhr:A.XMLHttpRequest&&(A.location.protocol!=="file:"||!A.ActiveXObject)?function(){return new A.XMLHttpRequest}:function(){try{return new A.ActiveXObject("Microsoft.XMLHTTP")}catch(a){}},accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},etag:{},ajax:function(a){function b(){e.success&& -e.success.call(k,o,i,x);e.global&&f("ajaxSuccess",[x,e])}function d(){e.complete&&e.complete.call(k,x,i);e.global&&f("ajaxComplete",[x,e]);e.global&&!--c.active&&c.event.trigger("ajaxStop")}function f(q,p){(e.context?c(e.context):c.event).trigger(q,p)}var e=c.extend(true,{},c.ajaxSettings,a),j,i,o,k=a&&a.context||e,n=e.type.toUpperCase();if(e.data&&e.processData&&typeof e.data!=="string")e.data=c.param(e.data,e.traditional);if(e.dataType==="jsonp"){if(n==="GET")N.test(e.url)||(e.url+=(ka.test(e.url)? -"&":"?")+(e.jsonp||"callback")+"=?");else if(!e.data||!N.test(e.data))e.data=(e.data?e.data+"&":"")+(e.jsonp||"callback")+"=?";e.dataType="json"}if(e.dataType==="json"&&(e.data&&N.test(e.data)||N.test(e.url))){j=e.jsonpCallback||"jsonp"+sb++;if(e.data)e.data=(e.data+"").replace(N,"="+j+"$1");e.url=e.url.replace(N,"="+j+"$1");e.dataType="script";A[j]=A[j]||function(q){o=q;b();d();A[j]=w;try{delete A[j]}catch(p){}z&&z.removeChild(C)}}if(e.dataType==="script"&&e.cache===null)e.cache=false;if(e.cache=== -false&&n==="GET"){var r=J(),u=e.url.replace(wb,"$1_="+r+"$2");e.url=u+(u===e.url?(ka.test(e.url)?"&":"?")+"_="+r:"")}if(e.data&&n==="GET")e.url+=(ka.test(e.url)?"&":"?")+e.data;e.global&&!c.active++&&c.event.trigger("ajaxStart");r=(r=xb.exec(e.url))&&(r[1]&&r[1]!==location.protocol||r[2]!==location.host);if(e.dataType==="script"&&n==="GET"&&r){var z=s.getElementsByTagName("head")[0]||s.documentElement,C=s.createElement("script");C.src=e.url;if(e.scriptCharset)C.charset=e.scriptCharset;if(!j){var B= -false;C.onload=C.onreadystatechange=function(){if(!B&&(!this.readyState||this.readyState==="loaded"||this.readyState==="complete")){B=true;b();d();C.onload=C.onreadystatechange=null;z&&C.parentNode&&z.removeChild(C)}}}z.insertBefore(C,z.firstChild);return w}var E=false,x=e.xhr();if(x){e.username?x.open(n,e.url,e.async,e.username,e.password):x.open(n,e.url,e.async);try{if(e.data||a&&a.contentType)x.setRequestHeader("Content-Type",e.contentType);if(e.ifModified){c.lastModified[e.url]&&x.setRequestHeader("If-Modified-Since", -c.lastModified[e.url]);c.etag[e.url]&&x.setRequestHeader("If-None-Match",c.etag[e.url])}r||x.setRequestHeader("X-Requested-With","XMLHttpRequest");x.setRequestHeader("Accept",e.dataType&&e.accepts[e.dataType]?e.accepts[e.dataType]+", */*":e.accepts._default)}catch(ga){}if(e.beforeSend&&e.beforeSend.call(k,x,e)===false){e.global&&!--c.active&&c.event.trigger("ajaxStop");x.abort();return false}e.global&&f("ajaxSend",[x,e]);var g=x.onreadystatechange=function(q){if(!x||x.readyState===0||q==="abort"){E|| -d();E=true;if(x)x.onreadystatechange=c.noop}else if(!E&&x&&(x.readyState===4||q==="timeout")){E=true;x.onreadystatechange=c.noop;i=q==="timeout"?"timeout":!c.httpSuccess(x)?"error":e.ifModified&&c.httpNotModified(x,e.url)?"notmodified":"success";var p;if(i==="success")try{o=c.httpData(x,e.dataType,e)}catch(v){i="parsererror";p=v}if(i==="success"||i==="notmodified")j||b();else c.handleError(e,x,i,p);d();q==="timeout"&&x.abort();if(e.async)x=null}};try{var h=x.abort;x.abort=function(){x&&h.call(x); -g("abort")}}catch(l){}e.async&&e.timeout>0&&setTimeout(function(){x&&!E&&g("timeout")},e.timeout);try{x.send(n==="POST"||n==="PUT"||n==="DELETE"?e.data:null)}catch(m){c.handleError(e,x,null,m);d()}e.async||g();return x}},handleError:function(a,b,d,f){if(a.error)a.error.call(a.context||a,b,d,f);if(a.global)(a.context?c(a.context):c.event).trigger("ajaxError",[b,a,f])},active:0,httpSuccess:function(a){try{return!a.status&&location.protocol==="file:"||a.status>=200&&a.status<300||a.status===304||a.status=== -1223||a.status===0}catch(b){}return false},httpNotModified:function(a,b){var d=a.getResponseHeader("Last-Modified"),f=a.getResponseHeader("Etag");if(d)c.lastModified[b]=d;if(f)c.etag[b]=f;return a.status===304||a.status===0},httpData:function(a,b,d){var f=a.getResponseHeader("content-type")||"",e=b==="xml"||!b&&f.indexOf("xml")>=0;a=e?a.responseXML:a.responseText;e&&a.documentElement.nodeName==="parsererror"&&c.error("parsererror");if(d&&d.dataFilter)a=d.dataFilter(a,b);if(typeof a==="string")if(b=== -"json"||!b&&f.indexOf("json")>=0)a=c.parseJSON(a);else if(b==="script"||!b&&f.indexOf("javascript")>=0)c.globalEval(a);return a},param:function(a,b){function d(i,o){if(c.isArray(o))c.each(o,function(k,n){b||/\[\]$/.test(i)?f(i,n):d(i+"["+(typeof n==="object"||c.isArray(n)?k:"")+"]",n)});else!b&&o!=null&&typeof o==="object"?c.each(o,function(k,n){d(i+"["+k+"]",n)}):f(i,o)}function f(i,o){o=c.isFunction(o)?o():o;e[e.length]=encodeURIComponent(i)+"="+encodeURIComponent(o)}var e=[];if(b===w)b=c.ajaxSettings.traditional; -if(c.isArray(a)||a.jquery)c.each(a,function(){f(this.name,this.value)});else for(var j in a)d(j,a[j]);return e.join("&").replace(yb,"+")}});var la={},Ab=/toggle|show|hide/,Bb=/^([+-]=)?([\d+-.]+)(.*)$/,W,va=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]];c.fn.extend({show:function(a,b){if(a||a===0)return this.animate(K("show",3),a,b);else{a=0;for(b=this.length;a").appendTo("body");f=e.css("display");if(f==="none")f="block";e.remove();la[d]=f}c.data(this[a],"olddisplay",f)}}a=0;for(b=this.length;a=0;f--)if(d[f].elem===this){b&&d[f](true);d.splice(f,1)}});b||this.dequeue();return this}});c.each({slideDown:K("show",1),slideUp:K("hide",1),slideToggle:K("toggle",1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"}},function(a,b){c.fn[a]=function(d,f){return this.animate(b,d,f)}});c.extend({speed:function(a,b,d){var f=a&&typeof a==="object"?a:{complete:d||!d&&b||c.isFunction(a)&&a,duration:a,easing:d&&b||b&&!c.isFunction(b)&&b};f.duration=c.fx.off?0:typeof f.duration=== -"number"?f.duration:c.fx.speeds[f.duration]||c.fx.speeds._default;f.old=f.complete;f.complete=function(){f.queue!==false&&c(this).dequeue();c.isFunction(f.old)&&f.old.call(this)};return f},easing:{linear:function(a,b,d,f){return d+f*a},swing:function(a,b,d,f){return(-Math.cos(a*Math.PI)/2+0.5)*f+d}},timers:[],fx:function(a,b,d){this.options=b;this.elem=a;this.prop=d;if(!b.orig)b.orig={}}});c.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this);(c.fx.step[this.prop]|| -c.fx.step._default)(this);if((this.prop==="height"||this.prop==="width")&&this.elem.style)this.elem.style.display="block"},cur:function(a){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]==null))return this.elem[this.prop];return(a=parseFloat(c.css(this.elem,this.prop,a)))&&a>-10000?a:parseFloat(c.curCSS(this.elem,this.prop))||0},custom:function(a,b,d){function f(j){return e.step(j)}this.startTime=J();this.start=a;this.end=b;this.unit=d||this.unit||"px";this.now=this.start; -this.pos=this.state=0;var e=this;f.elem=this.elem;if(f()&&c.timers.push(f)&&!W)W=setInterval(c.fx.tick,13)},show:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.show=true;this.custom(this.prop==="width"||this.prop==="height"?1:0,this.cur());c(this.elem).show()},hide:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.hide=true;this.custom(this.cur(),0)},step:function(a){var b=J(),d=true;if(a||b>=this.options.duration+this.startTime){this.now= -this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;for(var f in this.options.curAnim)if(this.options.curAnim[f]!==true)d=false;if(d){if(this.options.display!=null){this.elem.style.overflow=this.options.overflow;a=c.data(this.elem,"olddisplay");this.elem.style.display=a?a:this.options.display;if(c.css(this.elem,"display")==="none")this.elem.style.display="block"}this.options.hide&&c(this.elem).hide();if(this.options.hide||this.options.show)for(var e in this.options.curAnim)c.style(this.elem, -e,this.options.orig[e]);this.options.complete.call(this.elem)}return false}else{e=b-this.startTime;this.state=e/this.options.duration;a=this.options.easing||(c.easing.swing?"swing":"linear");this.pos=c.easing[this.options.specialEasing&&this.options.specialEasing[this.prop]||a](this.state,e,0,1,this.options.duration);this.now=this.start+(this.end-this.start)*this.pos;this.update()}return true}};c.extend(c.fx,{tick:function(){for(var a=c.timers,b=0;b
"; -a.insertBefore(b,a.firstChild);d=b.firstChild;f=d.firstChild;e=d.nextSibling.firstChild.firstChild;this.doesNotAddBorder=f.offsetTop!==5;this.doesAddBorderForTableAndCells=e.offsetTop===5;f.style.position="fixed";f.style.top="20px";this.supportsFixedPosition=f.offsetTop===20||f.offsetTop===15;f.style.position=f.style.top="";d.style.overflow="hidden";d.style.position="relative";this.subtractsBorderForOverflowNotVisible=f.offsetTop===-5;this.doesNotIncludeMarginInBodyOffset=a.offsetTop!==j;a.removeChild(b); -c.offset.initialize=c.noop},bodyOffset:function(a){var b=a.offsetTop,d=a.offsetLeft;c.offset.initialize();if(c.offset.doesNotIncludeMarginInBodyOffset){b+=parseFloat(c.curCSS(a,"marginTop",true))||0;d+=parseFloat(c.curCSS(a,"marginLeft",true))||0}return{top:b,left:d}},setOffset:function(a,b,d){if(/static/.test(c.curCSS(a,"position")))a.style.position="relative";var f=c(a),e=f.offset(),j=parseInt(c.curCSS(a,"top",true),10)||0,i=parseInt(c.curCSS(a,"left",true),10)||0;if(c.isFunction(b))b=b.call(a, -d,e);d={top:b.top-e.top+j,left:b.left-e.left+i};"using"in b?b.using.call(a,d):f.css(d)}};c.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),d=this.offset(),f=/^body|html$/i.test(b[0].nodeName)?{top:0,left:0}:b.offset();d.top-=parseFloat(c.curCSS(a,"marginTop",true))||0;d.left-=parseFloat(c.curCSS(a,"marginLeft",true))||0;f.top+=parseFloat(c.curCSS(b[0],"borderTopWidth",true))||0;f.left+=parseFloat(c.curCSS(b[0],"borderLeftWidth",true))||0;return{top:d.top- -f.top,left:d.left-f.left}},offsetParent:function(){return this.map(function(){for(var a=this.offsetParent||s.body;a&&!/^body|html$/i.test(a.nodeName)&&c.css(a,"position")==="static";)a=a.offsetParent;return a})}});c.each(["Left","Top"],function(a,b){var d="scroll"+b;c.fn[d]=function(f){var e=this[0],j;if(!e)return null;if(f!==w)return this.each(function(){if(j=wa(this))j.scrollTo(!a?f:c(j).scrollLeft(),a?f:c(j).scrollTop());else this[d]=f});else return(j=wa(e))?"pageXOffset"in j?j[a?"pageYOffset": -"pageXOffset"]:c.support.boxModel&&j.document.documentElement[d]||j.document.body[d]:e[d]}});c.each(["Height","Width"],function(a,b){var d=b.toLowerCase();c.fn["inner"+b]=function(){return this[0]?c.css(this[0],d,false,"padding"):null};c.fn["outer"+b]=function(f){return this[0]?c.css(this[0],d,false,f?"margin":"border"):null};c.fn[d]=function(f){var e=this[0];if(!e)return f==null?null:this;if(c.isFunction(f))return this.each(function(j){var i=c(this);i[d](f.call(this,j,i[d]()))});return"scrollTo"in -e&&e.document?e.document.compatMode==="CSS1Compat"&&e.document.documentElement["client"+b]||e.document.body["client"+b]:e.nodeType===9?Math.max(e.documentElement["client"+b],e.body["scroll"+b],e.documentElement["scroll"+b],e.body["offset"+b],e.documentElement["offset"+b]):f===w?c.css(e,d):this.css(d,typeof f==="string"?f:f+"px")}});A.jQuery=A.$=c})(window); diff --git a/docs/html/_static/minus.png b/docs/html/_static/minus.png deleted file mode 100644 index da1c562..0000000 Binary files a/docs/html/_static/minus.png and /dev/null differ diff --git a/docs/html/_static/plus.png b/docs/html/_static/plus.png deleted file mode 100644 index b3cb374..0000000 Binary files a/docs/html/_static/plus.png and /dev/null differ diff --git a/docs/html/_static/pygments.css b/docs/html/_static/pygments.css deleted file mode 100644 index 1a14f2a..0000000 --- a/docs/html/_static/pygments.css +++ /dev/null @@ -1,62 +0,0 @@ -.highlight .hll { background-color: #ffffcc } -.highlight { background: #eeffcc; } -.highlight .c { color: #408090; font-style: italic } /* Comment */ -.highlight .err { border: 1px solid #FF0000 } /* Error */ -.highlight .k { color: #007020; font-weight: bold } /* Keyword */ -.highlight .o { color: #666666 } /* Operator */ -.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ -.highlight .cp { color: #007020 } /* Comment.Preproc */ -.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ -.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ -.highlight .gd { color: #A00000 } /* Generic.Deleted */ -.highlight .ge { font-style: italic } /* Generic.Emph */ -.highlight .gr { color: #FF0000 } /* Generic.Error */ -.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ -.highlight .gi { color: #00A000 } /* Generic.Inserted */ -.highlight .go { color: #303030 } /* Generic.Output */ -.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ -.highlight .gs { font-weight: bold } /* Generic.Strong */ -.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ -.highlight .gt { color: #0040D0 } /* Generic.Traceback */ -.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ -.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ -.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ -.highlight .kp { color: #007020 } /* Keyword.Pseudo */ -.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ -.highlight .kt { color: #902000 } /* Keyword.Type */ -.highlight .m { color: #208050 } /* Literal.Number */ -.highlight .s { color: #4070a0 } /* Literal.String */ -.highlight .na { color: #4070a0 } /* Name.Attribute */ -.highlight .nb { color: #007020 } /* Name.Builtin */ -.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ -.highlight .no { color: #60add5 } /* Name.Constant */ -.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ -.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ -.highlight .ne { color: #007020 } /* Name.Exception */ -.highlight .nf { color: #06287e } /* Name.Function */ -.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ -.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ -.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ -.highlight .nv { color: #bb60d5 } /* Name.Variable */ -.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ -.highlight .w { color: #bbbbbb } /* Text.Whitespace */ -.highlight .mf { color: #208050 } /* Literal.Number.Float */ -.highlight .mh { color: #208050 } /* Literal.Number.Hex */ -.highlight .mi { color: #208050 } /* Literal.Number.Integer */ -.highlight .mo { color: #208050 } /* Literal.Number.Oct */ -.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ -.highlight .sc { color: #4070a0 } /* Literal.String.Char */ -.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ -.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ -.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ -.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ -.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ -.highlight .sx { color: #c65d09 } /* Literal.String.Other */ -.highlight .sr { color: #235388 } /* Literal.String.Regex */ -.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ -.highlight .ss { color: #517918 } /* Literal.String.Symbol */ -.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ -.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ -.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ -.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ -.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/docs/html/_static/searchtools.js b/docs/html/_static/searchtools.js deleted file mode 100644 index 663be4c..0000000 --- a/docs/html/_static/searchtools.js +++ /dev/null @@ -1,560 +0,0 @@ -/* - * searchtools.js_t - * ~~~~~~~~~~~~~~~~ - * - * Sphinx JavaScript utilties for the full-text search. - * - * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -/** - * helper function to return a node containing the - * search summary for a given text. keywords is a list - * of stemmed words, hlwords is the list of normal, unstemmed - * words. the first one is used to find the occurance, the - * latter for highlighting it. - */ - -jQuery.makeSearchSummary = function(text, keywords, hlwords) { - var textLower = text.toLowerCase(); - var start = 0; - $.each(keywords, function() { - var i = textLower.indexOf(this.toLowerCase()); - if (i > -1) - start = i; - }); - start = Math.max(start - 120, 0); - var excerpt = ((start > 0) ? '...' : '') + - $.trim(text.substr(start, 240)) + - ((start + 240 - text.length) ? '...' : ''); - var rv = $('
').text(excerpt); - $.each(hlwords, function() { - rv = rv.highlightText(this, 'highlighted'); - }); - return rv; -} - - -/** - * Porter Stemmer - */ -var Stemmer = function() { - - var step2list = { - ational: 'ate', - tional: 'tion', - enci: 'ence', - anci: 'ance', - izer: 'ize', - bli: 'ble', - alli: 'al', - entli: 'ent', - eli: 'e', - ousli: 'ous', - ization: 'ize', - ation: 'ate', - ator: 'ate', - alism: 'al', - iveness: 'ive', - fulness: 'ful', - ousness: 'ous', - aliti: 'al', - iviti: 'ive', - biliti: 'ble', - logi: 'log' - }; - - var step3list = { - icate: 'ic', - ative: '', - alize: 'al', - iciti: 'ic', - ical: 'ic', - ful: '', - ness: '' - }; - - var c = "[^aeiou]"; // consonant - var v = "[aeiouy]"; // vowel - var C = c + "[^aeiouy]*"; // consonant sequence - var V = v + "[aeiou]*"; // vowel sequence - - var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 - var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 - var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 - var s_v = "^(" + C + ")?" + v; // vowel in stem - - this.stemWord = function (w) { - var stem; - var suffix; - var firstch; - var origword = w; - - if (w.length < 3) - return w; - - var re; - var re2; - var re3; - var re4; - - firstch = w.substr(0,1); - if (firstch == "y") - w = firstch.toUpperCase() + w.substr(1); - - // Step 1a - re = /^(.+?)(ss|i)es$/; - re2 = /^(.+?)([^s])s$/; - - if (re.test(w)) - w = w.replace(re,"$1$2"); - else if (re2.test(w)) - w = w.replace(re2,"$1$2"); - - // Step 1b - re = /^(.+?)eed$/; - re2 = /^(.+?)(ed|ing)$/; - if (re.test(w)) { - var fp = re.exec(w); - re = new RegExp(mgr0); - if (re.test(fp[1])) { - re = /.$/; - w = w.replace(re,""); - } - } - else if (re2.test(w)) { - var fp = re2.exec(w); - stem = fp[1]; - re2 = new RegExp(s_v); - if (re2.test(stem)) { - w = stem; - re2 = /(at|bl|iz)$/; - re3 = new RegExp("([^aeiouylsz])\\1$"); - re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); - if (re2.test(w)) - w = w + "e"; - else if (re3.test(w)) { - re = /.$/; - w = w.replace(re,""); - } - else if (re4.test(w)) - w = w + "e"; - } - } - - // Step 1c - re = /^(.+?)y$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - re = new RegExp(s_v); - if (re.test(stem)) - w = stem + "i"; - } - - // Step 2 - re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - suffix = fp[2]; - re = new RegExp(mgr0); - if (re.test(stem)) - w = stem + step2list[suffix]; - } - - // Step 3 - re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - suffix = fp[2]; - re = new RegExp(mgr0); - if (re.test(stem)) - w = stem + step3list[suffix]; - } - - // Step 4 - re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; - re2 = /^(.+?)(s|t)(ion)$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - re = new RegExp(mgr1); - if (re.test(stem)) - w = stem; - } - else if (re2.test(w)) { - var fp = re2.exec(w); - stem = fp[1] + fp[2]; - re2 = new RegExp(mgr1); - if (re2.test(stem)) - w = stem; - } - - // Step 5 - re = /^(.+?)e$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - re = new RegExp(mgr1); - re2 = new RegExp(meq1); - re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); - if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) - w = stem; - } - re = /ll$/; - re2 = new RegExp(mgr1); - if (re.test(w) && re2.test(w)) { - re = /.$/; - w = w.replace(re,""); - } - - // and turn initial Y back to y - if (firstch == "y") - w = firstch.toLowerCase() + w.substr(1); - return w; - } -} - - -/** - * Search Module - */ -var Search = { - - _index : null, - _queued_query : null, - _pulse_status : -1, - - init : function() { - var params = $.getQueryParameters(); - if (params.q) { - var query = params.q[0]; - $('input[name="q"]')[0].value = query; - this.performSearch(query); - } - }, - - loadIndex : function(url) { - $.ajax({type: "GET", url: url, data: null, success: null, - dataType: "script", cache: true}); - }, - - setIndex : function(index) { - var q; - this._index = index; - if ((q = this._queued_query) !== null) { - this._queued_query = null; - Search.query(q); - } - }, - - hasIndex : function() { - return this._index !== null; - }, - - deferQuery : function(query) { - this._queued_query = query; - }, - - stopPulse : function() { - this._pulse_status = 0; - }, - - startPulse : function() { - if (this._pulse_status >= 0) - return; - function pulse() { - Search._pulse_status = (Search._pulse_status + 1) % 4; - var dotString = ''; - for (var i = 0; i < Search._pulse_status; i++) - dotString += '.'; - Search.dots.text(dotString); - if (Search._pulse_status > -1) - window.setTimeout(pulse, 500); - }; - pulse(); - }, - - /** - * perform a search for something - */ - performSearch : function(query) { - // create the required interface elements - this.out = $('#search-results'); - this.title = $('

' + _('Searching') + '

').appendTo(this.out); - this.dots = $('').appendTo(this.title); - this.status = $('

').appendTo(this.out); - this.output = $('
    ').appendTo(this.out); - - $('#search-progress').text(_('Preparing search...')); - this.startPulse(); - - // index already loaded, the browser was quick! - if (this.hasIndex()) - this.query(query); - else - this.deferQuery(query); - }, - - query : function(query) { - var stopwords = ["and","then","into","it","as","are","in","if","for","no","there","their","was","is","be","to","that","but","they","not","such","with","by","a","on","these","of","will","this","near","the","or","at"]; - - // Stem the searchterms and add them to the correct list - var stemmer = new Stemmer(); - var searchterms = []; - var excluded = []; - var hlterms = []; - var tmp = query.split(/\s+/); - var objectterms = []; - for (var i = 0; i < tmp.length; i++) { - if (tmp[i] != "") { - objectterms.push(tmp[i].toLowerCase()); - } - - if ($u.indexOf(stopwords, tmp[i]) != -1 || tmp[i].match(/^\d+$/) || - tmp[i] == "") { - // skip this "word" - continue; - } - // stem the word - var word = stemmer.stemWord(tmp[i]).toLowerCase(); - // select the correct list - if (word[0] == '-') { - var toAppend = excluded; - word = word.substr(1); - } - else { - var toAppend = searchterms; - hlterms.push(tmp[i].toLowerCase()); - } - // only add if not already in the list - if (!$.contains(toAppend, word)) - toAppend.push(word); - }; - var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); - - // console.debug('SEARCH: searching for:'); - // console.info('required: ', searchterms); - // console.info('excluded: ', excluded); - - // prepare search - var filenames = this._index.filenames; - var titles = this._index.titles; - var terms = this._index.terms; - var fileMap = {}; - var files = null; - // different result priorities - var importantResults = []; - var objectResults = []; - var regularResults = []; - var unimportantResults = []; - $('#search-progress').empty(); - - // lookup as object - for (var i = 0; i < objectterms.length; i++) { - var others = [].concat(objectterms.slice(0,i), - objectterms.slice(i+1, objectterms.length)) - var results = this.performObjectSearch(objectterms[i], others); - // Assume first word is most likely to be the object, - // other words more likely to be in description. - // Therefore put matches for earlier words first. - // (Results are eventually used in reverse order). - objectResults = results[0].concat(objectResults); - importantResults = results[1].concat(importantResults); - unimportantResults = results[2].concat(unimportantResults); - } - - // perform the search on the required terms - for (var i = 0; i < searchterms.length; i++) { - var word = searchterms[i]; - // no match but word was a required one - if ((files = terms[word]) == null) - break; - if (files.length == undefined) { - files = [files]; - } - // create the mapping - for (var j = 0; j < files.length; j++) { - var file = files[j]; - if (file in fileMap) - fileMap[file].push(word); - else - fileMap[file] = [word]; - } - } - - // now check if the files don't contain excluded terms - for (var file in fileMap) { - var valid = true; - - // check if all requirements are matched - if (fileMap[file].length != searchterms.length) - continue; - - // ensure that none of the excluded terms is in the - // search result. - for (var i = 0; i < excluded.length; i++) { - if (terms[excluded[i]] == file || - $.contains(terms[excluded[i]] || [], file)) { - valid = false; - break; - } - } - - // if we have still a valid result we can add it - // to the result list - if (valid) - regularResults.push([filenames[file], titles[file], '', null]); - } - - // delete unused variables in order to not waste - // memory until list is retrieved completely - delete filenames, titles, terms; - - // now sort the regular results descending by title - regularResults.sort(function(a, b) { - var left = a[1].toLowerCase(); - var right = b[1].toLowerCase(); - return (left > right) ? -1 : ((left < right) ? 1 : 0); - }); - - // combine all results - var results = unimportantResults.concat(regularResults) - .concat(objectResults).concat(importantResults); - - // print the results - var resultCount = results.length; - function displayNextItem() { - // results left, load the summary and display it - if (results.length) { - var item = results.pop(); - var listItem = $('
  • '); - if (DOCUMENTATION_OPTIONS.FILE_SUFFIX == '') { - // dirhtml builder - var dirname = item[0] + '/'; - if (dirname.match(/\/index\/$/)) { - dirname = dirname.substring(0, dirname.length-6); - } else if (dirname == 'index/') { - dirname = ''; - } - listItem.append($('').attr('href', - DOCUMENTATION_OPTIONS.URL_ROOT + dirname + - highlightstring + item[2]).html(item[1])); - } else { - // normal html builders - listItem.append($('').attr('href', - item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX + - highlightstring + item[2]).html(item[1])); - } - if (item[3]) { - listItem.append($(' (' + item[3] + ')')); - Search.output.append(listItem); - listItem.slideDown(5, function() { - displayNextItem(); - }); - } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { - $.get(DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' + - item[0] + '.txt', function(data) { - if (data != '') { - listItem.append($.makeSearchSummary(data, searchterms, hlterms)); - Search.output.append(listItem); - } - listItem.slideDown(5, function() { - displayNextItem(); - }); - }, "text"); - } else { - // no source available, just display title - Search.output.append(listItem); - listItem.slideDown(5, function() { - displayNextItem(); - }); - } - } - // search finished, update title and status message - else { - Search.stopPulse(); - Search.title.text(_('Search Results')); - if (!resultCount) - Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.')); - else - Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount)); - Search.status.fadeIn(500); - } - } - displayNextItem(); - }, - - performObjectSearch : function(object, otherterms) { - var filenames = this._index.filenames; - var objects = this._index.objects; - var objnames = this._index.objnames; - var titles = this._index.titles; - - var importantResults = []; - var objectResults = []; - var unimportantResults = []; - - for (var prefix in objects) { - for (var name in objects[prefix]) { - var fullname = (prefix ? prefix + '.' : '') + name; - if (fullname.toLowerCase().indexOf(object) > -1) { - var match = objects[prefix][name]; - var objname = objnames[match[1]][2]; - var title = titles[match[0]]; - // If more than one term searched for, we require other words to be - // found in the name/title/description - if (otherterms.length > 0) { - var haystack = (prefix + ' ' + name + ' ' + - objname + ' ' + title).toLowerCase(); - var allfound = true; - for (var i = 0; i < otherterms.length; i++) { - if (haystack.indexOf(otherterms[i]) == -1) { - allfound = false; - break; - } - } - if (!allfound) { - continue; - } - } - var descr = objname + _(', in ') + title; - anchor = match[3]; - if (anchor == '') - anchor = fullname; - else if (anchor == '-') - anchor = objnames[match[1]][1] + '-' + fullname; - result = [filenames[match[0]], fullname, '#'+anchor, descr]; - switch (match[2]) { - case 1: objectResults.push(result); break; - case 0: importantResults.push(result); break; - case 2: unimportantResults.push(result); break; - } - } - } - } - - // sort results descending - objectResults.sort(function(a, b) { - return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); - }); - - importantResults.sort(function(a, b) { - return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); - }); - - unimportantResults.sort(function(a, b) { - return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); - }); - - return [importantResults, objectResults, unimportantResults] - } -} - -$(document).ready(function() { - Search.init(); -}); \ No newline at end of file diff --git a/docs/html/_static/sidebar.js b/docs/html/_static/sidebar.js deleted file mode 100644 index a45e192..0000000 --- a/docs/html/_static/sidebar.js +++ /dev/null @@ -1,151 +0,0 @@ -/* - * sidebar.js - * ~~~~~~~~~~ - * - * This script makes the Sphinx sidebar collapsible. - * - * .sphinxsidebar contains .sphinxsidebarwrapper. This script adds - * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton - * used to collapse and expand the sidebar. - * - * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden - * and the width of the sidebar and the margin-left of the document - * are decreased. When the sidebar is expanded the opposite happens. - * This script saves a per-browser/per-session cookie used to - * remember the position of the sidebar among the pages. - * Once the browser is closed the cookie is deleted and the position - * reset to the default (expanded). - * - * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -$(function() { - // global elements used by the functions. - // the 'sidebarbutton' element is defined as global after its - // creation, in the add_sidebar_button function - var bodywrapper = $('.bodywrapper'); - var sidebar = $('.sphinxsidebar'); - var sidebarwrapper = $('.sphinxsidebarwrapper'); - - // for some reason, the document has no sidebar; do not run into errors - if (!sidebar.length) return; - - // original margin-left of the bodywrapper and width of the sidebar - // with the sidebar expanded - var bw_margin_expanded = bodywrapper.css('margin-left'); - var ssb_width_expanded = sidebar.width(); - - // margin-left of the bodywrapper and width of the sidebar - // with the sidebar collapsed - var bw_margin_collapsed = '.8em'; - var ssb_width_collapsed = '.8em'; - - // colors used by the current theme - var dark_color = $('.related').css('background-color'); - var light_color = $('.document').css('background-color'); - - function sidebar_is_collapsed() { - return sidebarwrapper.is(':not(:visible)'); - } - - function toggle_sidebar() { - if (sidebar_is_collapsed()) - expand_sidebar(); - else - collapse_sidebar(); - } - - function collapse_sidebar() { - sidebarwrapper.hide(); - sidebar.css('width', ssb_width_collapsed); - bodywrapper.css('margin-left', bw_margin_collapsed); - sidebarbutton.css({ - 'margin-left': '0', - 'height': bodywrapper.height() - }); - sidebarbutton.find('span').text('»'); - sidebarbutton.attr('title', _('Expand sidebar')); - document.cookie = 'sidebar=collapsed'; - } - - function expand_sidebar() { - bodywrapper.css('margin-left', bw_margin_expanded); - sidebar.css('width', ssb_width_expanded); - sidebarwrapper.show(); - sidebarbutton.css({ - 'margin-left': ssb_width_expanded-12, - 'height': bodywrapper.height() - }); - sidebarbutton.find('span').text('«'); - sidebarbutton.attr('title', _('Collapse sidebar')); - document.cookie = 'sidebar=expanded'; - } - - function add_sidebar_button() { - sidebarwrapper.css({ - 'float': 'left', - 'margin-right': '0', - 'width': ssb_width_expanded - 28 - }); - // create the button - sidebar.append( - '
    «
    ' - ); - var sidebarbutton = $('#sidebarbutton'); - light_color = sidebarbutton.css('background-color'); - // find the height of the viewport to center the '<<' in the page - var viewport_height; - if (window.innerHeight) - viewport_height = window.innerHeight; - else - viewport_height = $(window).height(); - sidebarbutton.find('span').css({ - 'display': 'block', - 'margin-top': (viewport_height - sidebar.position().top - 20) / 2 - }); - - sidebarbutton.click(toggle_sidebar); - sidebarbutton.attr('title', _('Collapse sidebar')); - sidebarbutton.css({ - 'color': '#FFFFFF', - 'border-left': '1px solid ' + dark_color, - 'font-size': '1.2em', - 'cursor': 'pointer', - 'height': bodywrapper.height(), - 'padding-top': '1px', - 'margin-left': ssb_width_expanded - 12 - }); - - sidebarbutton.hover( - function () { - $(this).css('background-color', dark_color); - }, - function () { - $(this).css('background-color', light_color); - } - ); - } - - function set_position_from_cookie() { - if (!document.cookie) - return; - var items = document.cookie.split(';'); - for(var k=0; k=e.computed&&(e={value:f,computed:g})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);var e={computed:Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;gf?1:0}),"value")};b.sortedIndex=function(a,c,d){d=d||b.identity;for(var e=0,f=a.length;e>1;d(a[g])=0})})};b.zip=function(){for(var a=b.toArray(arguments),c=b.max(b.pluck(a,"length")),d=new Array(c),e=0;e0?f-c:c-f)>=0)return e;e[g++]=f}};b.bind=function(a,c){var d=b.rest(arguments,2);return function(){return a.apply(c||j,d.concat(b.toArray(arguments)))}};b.bindAll=function(a){var c=b.rest(arguments);if(c.length==0)c=b.functions(a);b.each(c,function(d){a[d]=b.bind(a[d],a)}); -return a};b.delay=function(a,c){var d=b.rest(arguments,2);return setTimeout(function(){return a.apply(a,d)},c)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(b.rest(arguments)))};b.wrap=function(a,c){return function(){var d=[a].concat(b.toArray(arguments));return c.apply(c,d)}};b.compose=function(){var a=b.toArray(arguments);return function(){for(var c=b.toArray(arguments),d=a.length-1;d>=0;d--)c=[a[d].apply(this,c)];return c[0]}};b.keys=function(a){if(b.isArray(a))return b.range(0,a.length); -var c=[];for(var d in a)q.call(a,d)&&c.push(d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=function(a){return b.select(b.keys(a),function(c){return b.isFunction(a[c])}).sort()};b.extend=function(a,c){for(var d in c)a[d]=c[d];return a};b.clone=function(a){if(b.isArray(a))return a.slice(0);return b.extend({},a)};b.tap=function(a,c){c(a);return a};b.isEqual=function(a,c){if(a===c)return true;var d=typeof a;if(d!=typeof c)return false;if(a==c)return true;if(!a&&c||a&&!c)return false; -if(a.isEqual)return a.isEqual(c);if(b.isDate(a)&&b.isDate(c))return a.getTime()===c.getTime();if(b.isNaN(a)&&b.isNaN(c))return true;if(b.isRegExp(a)&&b.isRegExp(c))return a.source===c.source&&a.global===c.global&&a.ignoreCase===c.ignoreCase&&a.multiline===c.multiline;if(d!=="object")return false;if(a.length&&a.length!==c.length)return false;d=b.keys(a);var e=b.keys(c);if(d.length!=e.length)return false;for(var f in a)if(!b.isEqual(a[f],c[f]))return false;return true};b.isEmpty=function(a){return b.keys(a).length== -0};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=function(a){return!!(a&&a.concat&&a.unshift)};b.isArguments=function(a){return a&&b.isNumber(a.length)&&!b.isArray(a)&&!r.call(a,"length")};b.isFunction=function(a){return!!(a&&a.constructor&&a.call&&a.apply)};b.isString=function(a){return!!(a===""||a&&a.charCodeAt&&a.substr)};b.isNumber=function(a){return p.call(a)==="[object Number]"};b.isDate=function(a){return!!(a&&a.getTimezoneOffset&&a.setUTCFullYear)};b.isRegExp=function(a){return!!(a&& -a.test&&a.exec&&(a.ignoreCase||a.ignoreCase===false))};b.isNaN=function(a){return b.isNumber(a)&&isNaN(a)};b.isNull=function(a){return a===null};b.isUndefined=function(a){return typeof a=="undefined"};b.noConflict=function(){j._=n;return this};b.identity=function(a){return a};b.breakLoop=function(){throw m;};var s=0;b.uniqueId=function(a){var c=s++;return a?a+c:c};b.template=function(a,c){a=new Function("obj","var p=[],print=function(){p.push.apply(p,arguments);};with(obj){p.push('"+a.replace(/[\r\t\n]/g, -" ").replace(/'(?=[^%]*%>)/g,"\t").split("'").join("\\'").split("\t").join("'").replace(/<%=(.+?)%>/g,"',$1,'").split("<%").join("');").split("%>").join("p.push('")+"');}return p.join('');");return c?a(c):a};b.forEach=b.each;b.foldl=b.inject=b.reduce;b.foldr=b.reduceRight;b.filter=b.select;b.every=b.all;b.some=b.any;b.head=b.first;b.tail=b.rest;b.methods=b.functions;var l=function(a,c){return c?b(a).chain():a};b.each(b.functions(b),function(a){var c=b[a];i.prototype[a]=function(){var d=b.toArray(arguments); -o.call(d,this._wrapped);return l(c.apply(b,d),this._chain)}});b.each(["pop","push","reverse","shift","sort","splice","unshift"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){c.apply(this._wrapped,arguments);return l(this._wrapped,this._chain)}});b.each(["concat","join","slice"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){return l(c.apply(this._wrapped,arguments),this._chain)}});i.prototype.chain=function(){this._chain=true;return this};i.prototype.value=function(){return this._wrapped}})(); diff --git a/docs/html/_static/up-pressed.png b/docs/html/_static/up-pressed.png deleted file mode 100644 index 8bd587a..0000000 Binary files a/docs/html/_static/up-pressed.png and /dev/null differ diff --git a/docs/html/_static/up.png b/docs/html/_static/up.png deleted file mode 100644 index b946256..0000000 Binary files a/docs/html/_static/up.png and /dev/null differ diff --git a/docs/html/_static/websupport.js b/docs/html/_static/websupport.js deleted file mode 100644 index e9bd1b8..0000000 --- a/docs/html/_static/websupport.js +++ /dev/null @@ -1,808 +0,0 @@ -/* - * websupport.js - * ~~~~~~~~~~~~~ - * - * sphinx.websupport utilties for all documentation. - * - * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -(function($) { - $.fn.autogrow = function() { - return this.each(function() { - var textarea = this; - - $.fn.autogrow.resize(textarea); - - $(textarea) - .focus(function() { - textarea.interval = setInterval(function() { - $.fn.autogrow.resize(textarea); - }, 500); - }) - .blur(function() { - clearInterval(textarea.interval); - }); - }); - }; - - $.fn.autogrow.resize = function(textarea) { - var lineHeight = parseInt($(textarea).css('line-height'), 10); - var lines = textarea.value.split('\n'); - var columns = textarea.cols; - var lineCount = 0; - $.each(lines, function() { - lineCount += Math.ceil(this.length / columns) || 1; - }); - var height = lineHeight * (lineCount + 1); - $(textarea).css('height', height); - }; -})(jQuery); - -(function($) { - var comp, by; - - function init() { - initEvents(); - initComparator(); - } - - function initEvents() { - $('a.comment-close').live("click", function(event) { - event.preventDefault(); - hide($(this).attr('id').substring(2)); - }); - $('a.vote').live("click", function(event) { - event.preventDefault(); - handleVote($(this)); - }); - $('a.reply').live("click", function(event) { - event.preventDefault(); - openReply($(this).attr('id').substring(2)); - }); - $('a.close-reply').live("click", function(event) { - event.preventDefault(); - closeReply($(this).attr('id').substring(2)); - }); - $('a.sort-option').live("click", function(event) { - event.preventDefault(); - handleReSort($(this)); - }); - $('a.show-proposal').live("click", function(event) { - event.preventDefault(); - showProposal($(this).attr('id').substring(2)); - }); - $('a.hide-proposal').live("click", function(event) { - event.preventDefault(); - hideProposal($(this).attr('id').substring(2)); - }); - $('a.show-propose-change').live("click", function(event) { - event.preventDefault(); - showProposeChange($(this).attr('id').substring(2)); - }); - $('a.hide-propose-change').live("click", function(event) { - event.preventDefault(); - hideProposeChange($(this).attr('id').substring(2)); - }); - $('a.accept-comment').live("click", function(event) { - event.preventDefault(); - acceptComment($(this).attr('id').substring(2)); - }); - $('a.delete-comment').live("click", function(event) { - event.preventDefault(); - deleteComment($(this).attr('id').substring(2)); - }); - $('a.comment-markup').live("click", function(event) { - event.preventDefault(); - toggleCommentMarkupBox($(this).attr('id').substring(2)); - }); - } - - /** - * Set comp, which is a comparator function used for sorting and - * inserting comments into the list. - */ - function setComparator() { - // If the first three letters are "asc", sort in ascending order - // and remove the prefix. - if (by.substring(0,3) == 'asc') { - var i = by.substring(3); - comp = function(a, b) { return a[i] - b[i]; }; - } else { - // Otherwise sort in descending order. - comp = function(a, b) { return b[by] - a[by]; }; - } - - // Reset link styles and format the selected sort option. - $('a.sel').attr('href', '#').removeClass('sel'); - $('a.by' + by).removeAttr('href').addClass('sel'); - } - - /** - * Create a comp function. If the user has preferences stored in - * the sortBy cookie, use those, otherwise use the default. - */ - function initComparator() { - by = 'rating'; // Default to sort by rating. - // If the sortBy cookie is set, use that instead. - if (document.cookie.length > 0) { - var start = document.cookie.indexOf('sortBy='); - if (start != -1) { - start = start + 7; - var end = document.cookie.indexOf(";", start); - if (end == -1) { - end = document.cookie.length; - by = unescape(document.cookie.substring(start, end)); - } - } - } - setComparator(); - } - - /** - * Show a comment div. - */ - function show(id) { - $('#ao' + id).hide(); - $('#ah' + id).show(); - var context = $.extend({id: id}, opts); - var popup = $(renderTemplate(popupTemplate, context)).hide(); - popup.find('textarea[name="proposal"]').hide(); - popup.find('a.by' + by).addClass('sel'); - var form = popup.find('#cf' + id); - form.submit(function(event) { - event.preventDefault(); - addComment(form); - }); - $('#s' + id).after(popup); - popup.slideDown('fast', function() { - getComments(id); - }); - } - - /** - * Hide a comment div. - */ - function hide(id) { - $('#ah' + id).hide(); - $('#ao' + id).show(); - var div = $('#sc' + id); - div.slideUp('fast', function() { - div.remove(); - }); - } - - /** - * Perform an ajax request to get comments for a node - * and insert the comments into the comments tree. - */ - function getComments(id) { - $.ajax({ - type: 'GET', - url: opts.getCommentsURL, - data: {node: id}, - success: function(data, textStatus, request) { - var ul = $('#cl' + id); - var speed = 100; - $('#cf' + id) - .find('textarea[name="proposal"]') - .data('source', data.source); - - if (data.comments.length === 0) { - ul.html('
  • No comments yet.
    • '); - ul.data('empty', true); - } else { - // If there are comments, sort them and put them in the list. - var comments = sortComments(data.comments); - speed = data.comments.length * 100; - appendComments(comments, ul); - ul.data('empty', false); - } - $('#cn' + id).slideUp(speed + 200); - ul.slideDown(speed); - }, - error: function(request, textStatus, error) { - showError('Oops, there was a problem retrieving the comments.'); - }, - dataType: 'json' - }); - } - - /** - * Add a comment via ajax and insert the comment into the comment tree. - */ - function addComment(form) { - var node_id = form.find('input[name="node"]').val(); - var parent_id = form.find('input[name="parent"]').val(); - var text = form.find('textarea[name="comment"]').val(); - var proposal = form.find('textarea[name="proposal"]').val(); - - if (text == '') { - showError('Please enter a comment.'); - return; - } - - // Disable the form that is being submitted. - form.find('textarea,input').attr('disabled', 'disabled'); - - // Send the comment to the server. - $.ajax({ - type: "POST", - url: opts.addCommentURL, - dataType: 'json', - data: { - node: node_id, - parent: parent_id, - text: text, - proposal: proposal - }, - success: function(data, textStatus, error) { - // Reset the form. - if (node_id) { - hideProposeChange(node_id); - } - form.find('textarea') - .val('') - .add(form.find('input')) - .removeAttr('disabled'); - var ul = $('#cl' + (node_id || parent_id)); - if (ul.data('empty')) { - $(ul).empty(); - ul.data('empty', false); - } - insertComment(data.comment); - var ao = $('#ao' + node_id); - ao.find('img').attr({'src': opts.commentBrightImage}); - if (node_id) { - // if this was a "root" comment, remove the commenting box - // (the user can get it back by reopening the comment popup) - $('#ca' + node_id).slideUp(); - } - }, - error: function(request, textStatus, error) { - form.find('textarea,input').removeAttr('disabled'); - showError('Oops, there was a problem adding the comment.'); - } - }); - } - - /** - * Recursively append comments to the main comment list and children - * lists, creating the comment tree. - */ - function appendComments(comments, ul) { - $.each(comments, function() { - var div = createCommentDiv(this); - ul.append($(document.createElement('li')).html(div)); - appendComments(this.children, div.find('ul.comment-children')); - // To avoid stagnating data, don't store the comments children in data. - this.children = null; - div.data('comment', this); - }); - } - - /** - * After adding a new comment, it must be inserted in the correct - * location in the comment tree. - */ - function insertComment(comment) { - var div = createCommentDiv(comment); - - // To avoid stagnating data, don't store the comments children in data. - comment.children = null; - div.data('comment', comment); - - var ul = $('#cl' + (comment.node || comment.parent)); - var siblings = getChildren(ul); - - var li = $(document.createElement('li')); - li.hide(); - - // Determine where in the parents children list to insert this comment. - for(i=0; i < siblings.length; i++) { - if (comp(comment, siblings[i]) <= 0) { - $('#cd' + siblings[i].id) - .parent() - .before(li.html(div)); - li.slideDown('fast'); - return; - } - } - - // If we get here, this comment rates lower than all the others, - // or it is the only comment in the list. - ul.append(li.html(div)); - li.slideDown('fast'); - } - - function acceptComment(id) { - $.ajax({ - type: 'POST', - url: opts.acceptCommentURL, - data: {id: id}, - success: function(data, textStatus, request) { - $('#cm' + id).fadeOut('fast'); - $('#cd' + id).removeClass('moderate'); - }, - error: function(request, textStatus, error) { - showError('Oops, there was a problem accepting the comment.'); - } - }); - } - - function deleteComment(id) { - $.ajax({ - type: 'POST', - url: opts.deleteCommentURL, - data: {id: id}, - success: function(data, textStatus, request) { - var div = $('#cd' + id); - if (data == 'delete') { - // Moderator mode: remove the comment and all children immediately - div.slideUp('fast', function() { - div.remove(); - }); - return; - } - // User mode: only mark the comment as deleted - div - .find('span.user-id:first') - .text('[deleted]').end() - .find('div.comment-text:first') - .text('[deleted]').end() - .find('#cm' + id + ', #dc' + id + ', #ac' + id + ', #rc' + id + - ', #sp' + id + ', #hp' + id + ', #cr' + id + ', #rl' + id) - .remove(); - var comment = div.data('comment'); - comment.username = '[deleted]'; - comment.text = '[deleted]'; - div.data('comment', comment); - }, - error: function(request, textStatus, error) { - showError('Oops, there was a problem deleting the comment.'); - } - }); - } - - function showProposal(id) { - $('#sp' + id).hide(); - $('#hp' + id).show(); - $('#pr' + id).slideDown('fast'); - } - - function hideProposal(id) { - $('#hp' + id).hide(); - $('#sp' + id).show(); - $('#pr' + id).slideUp('fast'); - } - - function showProposeChange(id) { - $('#pc' + id).hide(); - $('#hc' + id).show(); - var textarea = $('#pt' + id); - textarea.val(textarea.data('source')); - $.fn.autogrow.resize(textarea[0]); - textarea.slideDown('fast'); - } - - function hideProposeChange(id) { - $('#hc' + id).hide(); - $('#pc' + id).show(); - var textarea = $('#pt' + id); - textarea.val('').removeAttr('disabled'); - textarea.slideUp('fast'); - } - - function toggleCommentMarkupBox(id) { - $('#mb' + id).toggle(); - } - - /** Handle when the user clicks on a sort by link. */ - function handleReSort(link) { - var classes = link.attr('class').split(/\s+/); - for (var i=0; iThank you! Your comment will show up ' - + 'once it is has been approved by a moderator.'); - } - // Prettify the comment rating. - comment.pretty_rating = comment.rating + ' point' + - (comment.rating == 1 ? '' : 's'); - // Make a class (for displaying not yet moderated comments differently) - comment.css_class = comment.displayed ? '' : ' moderate'; - // Create a div for this comment. - var context = $.extend({}, opts, comment); - var div = $(renderTemplate(commentTemplate, context)); - - // If the user has voted on this comment, highlight the correct arrow. - if (comment.vote) { - var direction = (comment.vote == 1) ? 'u' : 'd'; - div.find('#' + direction + 'v' + comment.id).hide(); - div.find('#' + direction + 'u' + comment.id).show(); - } - - if (opts.moderator || comment.text != '[deleted]') { - div.find('a.reply').show(); - if (comment.proposal_diff) - div.find('#sp' + comment.id).show(); - if (opts.moderator && !comment.displayed) - div.find('#cm' + comment.id).show(); - if (opts.moderator || (opts.username == comment.username)) - div.find('#dc' + comment.id).show(); - } - return div; - } - - /** - * A simple template renderer. Placeholders such as <%id%> are replaced - * by context['id'] with items being escaped. Placeholders such as <#id#> - * are not escaped. - */ - function renderTemplate(template, context) { - var esc = $(document.createElement('div')); - - function handle(ph, escape) { - var cur = context; - $.each(ph.split('.'), function() { - cur = cur[this]; - }); - return escape ? esc.text(cur || "").html() : cur; - } - - return template.replace(/<([%#])([\w\.]*)\1>/g, function() { - return handle(arguments[2], arguments[1] == '%' ? true : false); - }); - } - - /** Flash an error message briefly. */ - function showError(message) { - $(document.createElement('div')).attr({'class': 'popup-error'}) - .append($(document.createElement('div')) - .attr({'class': 'error-message'}).text(message)) - .appendTo('body') - .fadeIn("slow") - .delay(2000) - .fadeOut("slow"); - } - - /** Add a link the user uses to open the comments popup. */ - $.fn.comment = function() { - return this.each(function() { - var id = $(this).attr('id').substring(1); - var count = COMMENT_METADATA[id]; - var title = count + ' comment' + (count == 1 ? '' : 's'); - var image = count > 0 ? opts.commentBrightImage : opts.commentImage; - var addcls = count == 0 ? ' nocomment' : ''; - $(this) - .append( - $(document.createElement('a')).attr({ - href: '#', - 'class': 'sphinx-comment-open' + addcls, - id: 'ao' + id - }) - .append($(document.createElement('img')).attr({ - src: image, - alt: 'comment', - title: title - })) - .click(function(event) { - event.preventDefault(); - show($(this).attr('id').substring(2)); - }) - ) - .append( - $(document.createElement('a')).attr({ - href: '#', - 'class': 'sphinx-comment-close hidden', - id: 'ah' + id - }) - .append($(document.createElement('img')).attr({ - src: opts.closeCommentImage, - alt: 'close', - title: 'close' - })) - .click(function(event) { - event.preventDefault(); - hide($(this).attr('id').substring(2)); - }) - ); - }); - }; - - var opts = { - processVoteURL: '/_process_vote', - addCommentURL: '/_add_comment', - getCommentsURL: '/_get_comments', - acceptCommentURL: '/_accept_comment', - deleteCommentURL: '/_delete_comment', - commentImage: '/static/_static/comment.png', - closeCommentImage: '/static/_static/comment-close.png', - loadingImage: '/static/_static/ajax-loader.gif', - commentBrightImage: '/static/_static/comment-bright.png', - upArrow: '/static/_static/up.png', - downArrow: '/static/_static/down.png', - upArrowPressed: '/static/_static/up-pressed.png', - downArrowPressed: '/static/_static/down-pressed.png', - voting: false, - moderator: false - }; - - if (typeof COMMENT_OPTIONS != "undefined") { - opts = jQuery.extend(opts, COMMENT_OPTIONS); - } - - var popupTemplate = '\ -
    \ -

    \ - Sort by:\ - best rated\ - newest\ - oldest\ -

    \ -
    Comments
    \ -
    \ - loading comments...
    \ -
      \ -
      \ -

      Add a comment\ - (markup):

      \ -
      \ - reStructured text markup: *emph*, **strong**, \ - ``code``, \ - code blocks: :: and an indented block after blank line
      \ -
      \ - \ -

      \ - \ - Propose a change ▹\ - \ - \ - Propose a change ▿\ - \ -

      \ - \ - \ - \ - \ -
      \ -
      \ -
      '; - - var commentTemplate = '\ -
      \ -
      \ -
      \ - \ - \ - \ - \ - \ - \ -
      \ -
      \ - \ - \ - \ - \ - \ - \ -
      \ -
      \ -
      \ -

      \ - <%username%>\ - <%pretty_rating%>\ - <%time.delta%>\ -

      \ -
      <#text#>
      \ -

      \ - \ - reply ▿\ - proposal ▹\ - proposal ▿\ - \ - \ -

      \ - 
      \
-<#proposal_diff#>\
-
      \ -
        \ -
        \ -
        \ -
        \ - '; - - var replyTemplate = '\ -
      • \ -
        \ -
        \ - \ - \ - \ - \ - \ -
        \ -
        \ -
        • '; - - $(document).ready(function() { - init(); - }); -})(jQuery); - -$(document).ready(function() { - // add comment anchors for all paragraphs that are commentable - $('.sphinx-has-comment').comment(); - - // highlight search words in search results - $("div.context").each(function() { - var params = $.getQueryParameters(); - var terms = (params.q) ? params.q[0].split(/\s+/) : []; - var result = $(this); - $.each(terms, function() { - result.highlightText(this.toLowerCase(), 'highlighted'); - }); - }); - - // directly open comment window if requested - var anchor = document.location.hash; - if (anchor.substring(0, 9) == '#comment-') { - $('#ao' + anchor.substring(9)).click(); - document.location.hash = '#s' + anchor.substring(9); - } -}); diff --git a/docs/html/docs/background.html b/docs/html/docs/background.html deleted file mode 100644 index cbdda50..0000000 --- a/docs/html/docs/background.html +++ /dev/null @@ -1,168 +0,0 @@ - - - - - - - - - - Background — BAL 1.0 documentation - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Background¶

        -

        The algorithm used to calculate the BAL is based on Method 1 in the Australian Standard AS 3959 (2009)–Construction of buildings in bushfire-prone areas.

        -

        Method 1 is a simplified procedure that involves five steps to determine BAL, and is subject to limitations on the circumstances in which it can be used.

        -

        Limitation: This method doesn’t apply to the circumstances where the effective slope under the classified vegetation is more than 20 degrees downslope.

        -
        -

        Procedure to determine BAL¶

        -

        According to the Standard AS 3959 (2009), five steps are involved to calculate BAL.

        -

        Step 1: Select the relevant FDI based on the locations according to Table 2.1 in the Australian Standard AS 3959 (2009). For example, from Table 2.1, the FDI for Western Australia is 80.

        -

        Step 2: Reclassify the input vegetation dataset into seven vegetation types defined in Table 2.3 in the Standard AS 3959 (2009).

        -
          -
        • 1: Forest,
          • -
        • 2: Woodland,
          • -
        • 3: Shrubland,
          • -
        • 4: Scrub,
          • -
        • 5: Mallee/Mulga,
          • -
        • 6: Rainforest,
          • -
        • 7: Grassland/Tussock moorland.
          • -
        -

        The numbers from 1 to 7 are assigned to these vegetation classes respectively for calculating BAL.

        -

        Step 3: Calculate the distance of the site from the classified vegetation. According to AS 3959 (2009), the vegetation is considered when its distance from the site of interest is within 100 metres.

        -

        Step 4: Determine the effective slopes (the gradient from each cell) and their aspects under the classified vegetation types. If a slope’s aspect is in the same direction as the vegetation from the site, this slope is regarded as a downslope that will be further analysed. Otherwise the slope is regarded as an upslope.

        -

        When calculating BAL, upslopes and flat lands are treated as a single category. For downslopes, the Standard breaks them down into five classes:

        -
          -
        • 0 < downslope <= 5 degrees
          • -
        • 5 < downslope <= 10 degrees
          • -
        • 10 < downslope <= 15 degrees
          • -
        • 15 < downslope <= 20 degrees
          • -
        • > 20 degrees (beyond consideration of Method 1)
          • -
        -

        Step 5: Determine the BAL from an appropriate table defined in AS 3959 (2009) based on the input FDI. For example, for Western Australia, the FDI is 80 and thus Table 2.4.3 is adopted for deriving the BAL.

        -
        -
        -

        Deriving and interpreting BAL¶

        -

        We consider eight cardinal directions: north, northeast, east, southeast, south, southwest, west, and northwest.

        -

        For each cardinal direction, we consider the neighbouring cells up to 100 metres from the site. We calculate the BAL for each neighbouring cell with regards to the site based on the neighbouring cell’s vegetation type, upslope or downslope degrees, and its distance to the site.

        -

        The BAL falls into a list of (12.5, 19, 29, 40, 100), where 100 represents Fire Zone (FZ). There is one more circumstances beyond Method 1 in AS 3959 (2009).

        -
          -
        • Where the downslope is greater than 20 degrees and there is vegetation, a constant value of 200 is given to the BAL.
          • -
        -

        The maximum BAL is selected among all neighbouring cells in a given cardinal direction to represent the BAL for that direction.

        -

        The final BAL for the site of interest is determined by selecting the maximum BAL from all eight cardinal directions.

        -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Previous topic

        -

        Introduction

        -

        Next topic

        -

        Installation

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/bal.html b/docs/html/docs/bal.html deleted file mode 100644 index 3b32b13..0000000 --- a/docs/html/docs/bal.html +++ /dev/null @@ -1,312 +0,0 @@ - - - - - - - - - - Bushfire Attack Level — BAL 1.0 documentation - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Bushfire Attack Level¶

        -
        -

        bal.py¶

        -
        -

        bal - Calculate the bushfire attack level (BAL)¶

        -

        This module is used to produce the bushfire attack level (BAL) for an area of -interest within Australia based on input vegetation and elevation datasets -as per Method 1 in the Australian Standard AS 3959 (2009) – Construction of -buildings in bushfire-prone areas.

        - --- - - - -
        moduleauthor:Tina Yang <tina.yang@ga.gov.au>
        -
        -
        -bal.bal_calc(vegetation, dem, fdi, output_folder, remap, mask)[source]¶
        -

        Calcuate BAL based on vegetation map and DEM.

        - --- - - - -
        Parameters:
          -
        • vegetation – file the original vegetation
          • -
        • dem – file the input DEM
          • -
        • fdi – int the input FDI value
          • -
        • output_folder – str the output folder
          • -
        • remap – srt the vegetation reclassification
          • -
        • mask – file the mask for the effective area of interest (AOI)
          • -
        -
        -
        - -
        -
        -bal.find_aoi(extent, dem, veg)[source]¶
        -

        Find the effective area of interest based on input vegetation map, DEM and -extent.

        - --- - - - - - -
        Parameters:
          -
        • extent – str the input extent
          • -
        • dem – file the input DEM
          • -
        • veg – file the input vegetation
          • -
        -
        Returns:

        file the mask for effective AOI

        -
        -
        - -
        -
        -bal.find_common_area(veg_class, slope, aspect)[source]¶
        -

        Find the common area of vegetation, slope and aspect to calculate BAL.

        - --- - - - - - - - - - -
        Parameters:
          -
        • veg_class – file the reclassified vegetation
          • -
        • slope – file the slope derived from DEM
          • -
        • aspect – file the aspect derived from DEM
          • -
        -
        Returns:

        file the vegetation in common area

        -
        Returns:

        file the slope in common area

        -
        Returns:

        file the aspect in common area

        -
        -
        - -
        -
        -bal.get_extent_mask(extent, mask)[source]¶
        -

        Derive the mask for the customised input extent.

        - --- - - - -
        Parameters:
          -
        • extent – str the input extent
          • -
        • mask – file the output mask
          • -
        -
        -
        - -
        -
        -bal.get_footprint(raster, footprint)[source]¶
        -

        Find the footprint of a raster

        - --- - - - -
        Parameters:
          -
        • raster – file the input raster
          • -
        • footprint – file the output footprint
          • -
        -
        -
        - -
        -
        -bal.get_slope_aspect(input_dem, output_folder, mask)[source]¶
        -

        Calculate the slope and aspect from the input DEM

        - --- - - - - - - - -
        Parameters:
          -
        • input_dem – file the input DEM
          • -
        • output_folder – str the output folder
          • -
        • mask – file the mask for the effective AOI
          • -
        -
        Returns:

        file the reclassified slope

        -
        Returns:

        file the reclassified aspect

        -
        -
        - -
        -
        -bal.reclass_veg(veg, dem, output_folder, remap, mask)[source]¶
        -

        Reclassify the original vegetation into the categories classified as Table -2.3 in AS 3959 (2009).

        - --- - - - - - -
        Parameters:
          -
        • veg – file the input vegetation
          • -
        • dem – file the input dem used as reference projection
          • -
        • output_folder – str the output folder
          • -
        • remap – srt the vegetation reclassification
          • -
        • mask – file the mask for the effective AOI
          • -
        -
        Returns:

        file the reclassified vegetation

        -
        -
        - -
        -
        -bal.run()[source]¶
        -

        Run the BAL calculations.

        -
        - -
        -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Previous topic

        -

        An Example

        -

        Next topic

        -

        Calculate_bal

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/calculate_bal.html b/docs/html/docs/calculate_bal.html deleted file mode 100644 index e371af1..0000000 --- a/docs/html/docs/calculate_bal.html +++ /dev/null @@ -1,278 +0,0 @@ - - - - - - - - - - Calculate_bal — BAL 1.0 documentation - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Calculate_bal¶

        -
        -

        calculate_bal.py¶

        -

        calculate_bal - essential part of calculating the -bushfire attack level (BAL)

        -
        -

        This module includes algorithms that are used to calculate BAL as per -Method 1 in the Australian Standard AS 3959 (2009) – Construction of -buildings in bushfire-prone areas.

        - --- - - - -
        moduleauthor:Tina Yang <tina.yang@ga.gov.au>
        -
        -
        -calculate_bal.bal_cal(veg_class, slope, aspect, fdi)[source]¶
        -

        Calculate the BAL based on the classified vegetation and the combined -slope and vegetation according to an appropriate table in AS 3959 (2009) -to determine the bushfire attack level (BAL).

        - --- - - - -
        Parameters:
          -
        • veg_class – file the input classified vegetation
          • -
        • slope – file the input slope
          • -
        • aspect – file the input aspect
          • -
        • fdi – int the input FDI value
          • -
        -
        -
        - -
        -
        -calculate_bal.bal_esti(veg, dist, slope, fdi)[source]¶
        -

        Calculate the BAL based on the vegetation class, slope degree and -horizontal distance from the point of interest (POI).

        - --- - - - - - -
        Parameters:
          -
        • veg – float the vegetation type
          • -
        • dist – float the horizontal distance from POI
          • -
        • slope – float the slope value
          • -
        • fdi – int the input FDI value
          • -
        -
        Returns:

        float the output BAL value for this neighbour point regards to -the POI

        -
        -
        - -
        -
        -calculate_bal.convo(a_dir, veg_data, slope_data, aspect_data, pixel_width, fdi)[source]¶
        -

        Find the maximum BAL for the point of interest in one direction by -assessing all neighbours’ BAL values in that direction (up to 100 metres).

        - --- - - - - - -
        Parameters:
          -
        • a_dir – string the specific direction
          • -
        • veg_data – numpy.ndarray the classified vegetation values
          • -
        • slope_data – numpy.ndarray the slope values
          • -
        • aspect_data – numpy.ndarray the aspect values
          • -
        • pixel_width – float the pixel width of the classified vegetation
          • -
        • fdi – int the input FDI value
          • -
        -
        Returns:

        numpy.ndarray the output BAL values

        -
        -
        - -
        -
        -calculate_bal.find_dist_class(dist, dist_limit)[source]¶
        -

        Decide the BAL class based on the input distance and the distance -upper-limit for each BAL class.

        - --- - - - - - -
        Parameters:
          -
        • dist – float the horizontal distance from POI
          • -
        • dist_limit – list the upper-limit for each BAL class
          • -
        -
        Returns:

        int the distance class defined in bal_database.py

        -
        -
        - -
        -
        -calculate_bal.get_max_bal(bal_list)[source]¶
        -

        get the maximum bal value of all 8 directions.

        - --- - - - - - -
        Parameters:bal_list – list of arrays the bal value for each of 8 directions
        Returns:numpy.ndarray the maximum bal value of 8 directions
        -
        - -
        -
        -calculate_bal.get_slope_in_aspect(slope_data, aspect_data, rows, cols, aspect_value)[source]¶
        -

        Get the slope data in a specific aspect.

        - --- - - - - - -
        Parameters:
          -
        • slope_data – numpy.ndarray the slope values
          • -
        • aspect_data – numpy.ndarray the aspect values
          • -
        • rows – int the row number of the slope_data
          • -
        • cols – int the column number of the slope_data
          • -
        • aspect_value – int the aspect value
          • -
        -
        Returns:

        numpy.ndarray the slope data in an aspect

        -
        -
        - -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Previous topic

        -

        Bushfire Attack Level

        -

        Next topic

        -

        utilities

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/disclaim.html b/docs/html/docs/disclaim.html deleted file mode 100644 index c8ced53..0000000 --- a/docs/html/docs/disclaim.html +++ /dev/null @@ -1,121 +0,0 @@ - - - - - - - - - - Disclaimer — BAL 1.0 documentation - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Disclaimer¶

        -

        Geoscience Australia has tried to make the information in this product as accurate as possible. However, it does not guarantee that the information produced by this product is totally accurate or complete. Therefore, users should use the BAL values derived from the BAL toolbox as an indicative guide only, and should not solely rely on this information when making a decision.

        -

        This work was produced at Geoscience Australia. Neither the Australian Government, Geoscience Australia nor any of their employees, makes any warranty, express or implied, or assumes any liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately-owned rights. Reference herein to any specific commercial products, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the Australian Government or Geoscience Australia. The views and opinions of authors expressed herein do not necessarily state or reflect those of the Australian Government or Geoscience Australia, and shall not be used for advertising or product endorsement purposes.

        -

        This document does not convey a warranty, express or implied, of merchantability or fitness for a particular purpose.

        -
        - - -
        -
        -
        -
        -
        -

        Previous topic

        -

        Bushfire Attack Level

        -

        Next topic

        -

        Introduction

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/examples.html b/docs/html/docs/examples.html deleted file mode 100644 index f56712f..0000000 --- a/docs/html/docs/examples.html +++ /dev/null @@ -1,172 +0,0 @@ - - - - - - - - - - An Example — BAL 1.0 documentation - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        An Example¶

        -
        -

        Input¶

        -

        Input DEM:

        -

        jerram_dem: Esri Grid format, MGA 50, 25 m resolution. See Figure 4.8. The input DEM is located under the examples\input folder.

        -
        -Example DEM data at Jerramungup, WA. -

        Example DEM data at Jerramungup, WA.

        -
        -

        Input vegetation:

        -

        jerram_veg: Esri Grid format, GDA 1994 Australia Albers, 100 m resolution. See Figure 4.9. The input vegetation dataset is located under the examples\input folder.

        -
        -Example vegetation data at Jerramungup, WA. -

        Example vegetation data at Jerramungup, WA.

        -
        -

        Input vegetation reclassification map:

        -

        There are many classes in the original vegetation. To derive the target vegetation classes described in the Standard (1: Forest, 2: Woodland, 3: Shrubland, 4: Scrub, 5: Mallee/Mulga, 6: Rainforest, 7: Grassland/Tussock moorland.), the remap string is defined as: “1 6;2 1;3 1;4 1;5 13 2;14 5;15 18 3;19 22 7;23 4;24 25 NODATA;26 4;27 28 NODATA;29 4;30 1;31 2;32 5;99 NODATA”.

        -

        Output path:

        -

        The example output path is C:\github\bal\examples\output.

        -

        FDI value:

        -

        Default value 80 is selected.

        -

        Extent:

        -

        Default is selected.

        -

        After all input parameters are defined, the fields in the BAL calculation window are all populated. See Figure 4.10.

        -
        -Example input parameters within BAL calculation window. -

        Example input parameters within BAL calculation window.

        -
        -
        -
        -

        Process¶

        -

        After clicking the OK button in the above window, the calculation starts running with a progress reporting in a pop-up window. When it finishes successfully, the pop-up window looks like Figure 4.11.

        -
        -Example pop-up window when the calculation finishes. -

        Example pop-up window when the calculation finishes.

        -
        -
        -
        -

        Output¶

        -

        Nine rasters are produced under C:\github\bal\examples\output. Figure 4.12 displays the maximum BAL raster file named as bal_max.img for this example.

        -
        -Example output BAL at Jerramungup, WA. -

        Example output BAL at Jerramungup, WA.

        -
        -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Previous topic

        -

        Running the tool

        -

        Next topic

        -

        Bushfire Attack Level

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/execution.html b/docs/html/docs/execution.html deleted file mode 100644 index 79e8f26..0000000 --- a/docs/html/docs/execution.html +++ /dev/null @@ -1,191 +0,0 @@ - - - - - - - - - - Running the tool — BAL 1.0 documentation - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Running the tool¶

        -

        To calculate the BAL, we use the BAL calculation tool within the BAL toolbox installed in ArcGIS 10.2.

        -

        Select the BAL calculation tool within the BAL toolbox, see Figure 4.5.

        -
        -Select the tool **BAL calculation**. -

        Select the tool BAL calculation.

        -
        -

        Then the BAL calculation window is open, see Figure 4.6.

        -
        -The **BAL calculation** window. -

        The BAL calculation window.

        -
        -
        -

        Parameters within the tool¶

        -

        Input DEM raster:

        -
        -
        Open the input DEM file from a specific location. The DEM is required to be in a projected coordinate system with linear unit metre. For example GDA94 / MGA zone 50 is a projected spatial reference system and is suitable for use in the western part of Western Australia. More information about GDA94 / MGA zone 50 can be found here.
        -

        Input vegetation raster:

        -
        -
        Open the input vegetation dataset from the location same as the input DEM. The vegetation dataset can be in either a geographical or a projected coordinate system. It will be reprojected to the same projection and same resolution as DEM by the BAL tool.
        -

        Vegetation reclassification:

        -
        -

        Reclassify the input vegetation classes into those defined in the Australian Standard AS 3959 (2009). There are seven classes defined in the Standard. In this tool, we give each class a unique number, i.e.:

        -
          -
        • 1: Forest,
          • -
        • 2: Woodland,
          • -
        • 3: Shrubland,
          • -
        • 4: Scrub,
          • -
        • 5: Mallee/Mulga,
          • -
        • 6: Rainforest,
          • -
        • 7: Grassland/Tussock moorland.
          • -
        -

        A sample reclassification map is entered for the example data. The reclassification map needs to be changed by the users according to their own input vegetation data.

        -
        -

        Output path:

        -
        -
        Define the output location.
        -

        FDI value:

        -
        -

        The input Fire Danger Index (FDI) value has four choices (100, 80, 50, 40) based on the locations, which are specified in the Australian Standard AS 3959 (2009).

        -
          -
        • 100: Australian Capital Territory (ACT), part of New South Wales (NSW) (Greater Hunter, Greater Sydney, Illawarra/Shoalhaven, Far South Coast and Southern Ranges fire weather districts), and Victoria general (excluding alpine areas).
          • -
        • 80: NSW general (excluding alpine areas, and the areas with FDI 100), South Australia (SA), and Western Australia (WA).
          • -
        • 50: NSW alpine areas, Tasmania, and Victoria alpine areas.
          • -
        • 40: Northern Territory (NT), and Queensland (Qld).
          • -
        -

        Select the FDI value from a suite of values (100, 80, 50, 40). It is optional. The default value is 80 that is applicable in Western Australia.

        -
        -

        Extent:

        -
        -
        The extent is used to select the area of interest for which BAL will be calculated. The output data extent will be where you have consistent coverage of DEM and vegetation data within the area of interest.
        -

        Note:

        -
          -
        • There is a limitation in raster file name length and file path length in ArcGIS. For a raster name in ESRI Grid format, the maximum number of characters is 13 and for full path name, the maximum number of character is 128. For more information, click here. In addition, as tested, each folder name’s length should be restricted to at most eight characters.
          • -
        • The script requires that the input DEM and vegetation dataset are in the same location. The tool will fail to run when the input DEM and vegetation datasets are not in the same folder.
          • -
        -
        -
        -

        Output¶

        -

        A suite of rasters are produced and stored in the output folder. They represent the BAL for the area computed in each of eight cardinal directions (E, S, W, N, NE, NW, SE and SW) and the maximum BAL of all directions. Figure 4.7 is an example output.

        -
        -An example BAL output window. -

        An example BAL output window.

        -
        -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Previous topic

        -

        Setting up the toolbox

        -

        Next topic

        -

        An Example

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/install.html b/docs/html/docs/install.html deleted file mode 100644 index 364afe4..0000000 --- a/docs/html/docs/install.html +++ /dev/null @@ -1,161 +0,0 @@ - - - - - - - - - - Installation — BAL 1.0 documentation - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Installation¶

        -

        Installing BAL Toolbox is intended to be a simple process, requiring only basic understanding of ArcGIS toolbox operations. It has been installed and tested on ArcGIS 10.2.

        -
        -

        Unzipping the toolbox¶

        -

        The software package is delivered as a compressed zip file. Unzip the toolbox into a location on your computer, for example C:\bal. Then you will have stored all the files at folder C:\bal.

        -
        -
        -

        Dependencies¶

        -

        This toolbox is developed and tested within ArcGIS 10.2 that integrates with Python 2.7 and Numpy 1.6.2. It is not recommended to install an independent version of Python for use in ArcGIS. Using a different version of Python may lead to compatibility issues.

        -

        However, if necessary, there are several ways to obtain the required libraries – using Python’s recommended tool pip, installing a distribution such as Python(x,y) package (for Windows environments), or installing the libraries from source or binary installers (pre-compiled binary Windows installer versions for all the libraries (both 32-bit and 64-bit) can be obtained here).

        -

        For detailed instructions on installation of these dependencies, please see the documentation for each individual library.

        - -
        -
        -

        Setting the environment¶

        -

        To enable BAL toolbox to run flawlessly, you may need to change some environment settings. The important variable to set is the PYTHONPATH variable. This should be set to the path where you have extracted the contents of the zip file. A complete discussion on environment variables in Python is given in the Python documentation.

        -
        -

        Windows¶

        -

        The Python documentation contains some simple instructions for setting environment variables on Windows systems here. See this link for setting the variables on different Windows systems.

        -
        -
        -
        -

        Testing the installation¶

        -

        The code includes a suite of unit tests that ensure elements of the code base work as expected. The code should be tested before running the toolbox.

        -

        The test suite can be run from the main directory. On Windows, run the run_test_all.cmd script from the main BAL directory.

        -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Previous topic

        -

        Background

        -

        Next topic

        -

        Setting up the toolbox

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/intro.html b/docs/html/docs/intro.html deleted file mode 100644 index aa40544..0000000 --- a/docs/html/docs/intro.html +++ /dev/null @@ -1,155 +0,0 @@ - - - - - - - - - - Introduction — BAL 1.0 documentation - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Introduction¶

        -

        Fire is a natural feature of the Australian landscape and remains an ever-present threat. Bushfire threat analysis aims to inform the fire authorities and the community of the bushfire hazard in an effort to manage the risk posed to life, property and the environment.

        -

        Bushfire Attack Level (BAL) is a measure of the severity of a building’s potential exposure to bushfire. It is defined in the Australian Standard AS 3959 (2009)–Construction of buildings in bushfire-prone areas, to serve as a basis for establishing the requirements for construction, to improve the protection of buildings from bushfire attack. The Standard describes how to compute the bushfire attack level for any location and directly links this to recommendations on the design of existing or planned buildings.

        -

        The BAL toolbox implements the rules described by Method 1 in AS 3959 (2009) by integrating them into a computational code that can be run in the ESRI ArcGIS 10.2 environment.

        -
        -

        Package structures¶

        -

        The toolbox name is BAL.tbx. This toolbox is associated with a python script, bal.py, to derive BAL. The script bal.py links to a python script calculate_bal.py and a module Utilities, which includes supporting dictionaries defined in two python scripts:

        -
          -
        • value_lookup.py;
          • -
        • bal_database.py.
          • -
        -

        There are three more folders:

        -
          -
        • docs: holding the documentation files.
          • -
        • tests: holding the unit tests, scenario tests and their test data.
          • -
        • examples: holding the example input and output data.
          • -
        -
        -
        -

        Use limitations¶

        -

        The BAL tool developed in Geoscience Australia (GA) has been developed and tested in ArcGIS 10.2. However, GA does not guarantee that the information derived is totally accurate or complete. Therefore, you should not solely rely on this information. Key limitations/approximations include the following:

        -
          -
        • The BAL is produced based on the simplified method (Method 1) in AS 3959 (2009). When the land downslope is more than 20 degrees, more detailed method (Method 2) should be adopted. Method 2 has not been incorporated into the toolbox developed. Instead, a constant value of 200 is provided as BAL for such circumstances.
          • -
        • Elevation data is a critical input of the tool. Digital Elevation Model (DEM) with finer resolution usually leads to more accurate BAL results. The example data uses a DEM with a resolution of 1 second of arc (approximate 30 m by 30 m grid cell at the equator), the best available national scale elevation dataset at the time of modelling. As with all spatial analyses, the results are sensitive to the input DEM’s quality, resolution, coverage and currency and should therefore be used with this understanding.
          • -
        • Vegetation data is another critical input into the tool. Method 1 in AS 3959 (2009) considers the vegetation up to 100 metres from the site of interest. Ideally the vegetation with finer resolution (preferred at metre level) is required to derive sensible BAL analyses. Where finer vegetation data is not available, the alternative coarse vegetation data may lead to inaccurate output BAL.
          • -
        • The BAL toolbox is intended to run in the ArcGIS toolbox environment and is not intended to run in a Python script environment.
          • -
        • This software algorithm adapts to the Method 1 in AS 3959 (2009) by modelling it spatially. Readers are assumed to be familiar with AS 3959 (2009). For the detailed description of the Method 1, please refer to the Standard AS 3959 (2009).
          • -
        -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Previous topic

        -

        Disclaimer

        -

        Next topic

        -

        Background

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/setup.html b/docs/html/docs/setup.html deleted file mode 100644 index 703d124..0000000 --- a/docs/html/docs/setup.html +++ /dev/null @@ -1,159 +0,0 @@ - - - - - - - - - - Setting up the toolbox — BAL 1.0 documentation - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Setting up the toolbox¶

        -
        -

        Adding the toolbox into ArcGIS 10.2¶

        -

        Follow the steps below to add the toolbox into ArcGIS 10.2:

        -
          -
        • Open the ArcToolBox window. See Figure 4.1.
          • -
        -
        -ArcToolbox window. -

        The ArcToolbox window.

        -
        -
          -
        • Right click ArcToolbox at the top of the window, see Figure 4.2.
          • -
        -
        -Right click ArcToolbox in the ArcToolbox window. -

        Right click ArcToolbox in the ArcToolbox window.

        -
        -
          -
        • Select Add Toolbox..., a dialog box is open. See Figure 4.3.
          • -
        -
        -addtoolbox dialog window. -

        The Add Toolbox dialog window.

        -
        -
          -
        • In the dialog box, navigate to the location of the package, for example C:\bal, you will find the BAL.tbx. See Figure 4.3.
          • -
        • Select BAL.tbx and click Open, a new toolbox called BAL is added to the ArcToolbox. See Figure 4.4.
          • -
        -
        -Bal toolbox is added. -

        The Bal toolbox is added.

        -
        -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Previous topic

        -

        Installation

        -

        Next topic

        -

        Running the tool

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/tests.html b/docs/html/docs/tests.html deleted file mode 100644 index 8644900..0000000 --- a/docs/html/docs/tests.html +++ /dev/null @@ -1,237 +0,0 @@ - - - - - - - - - - tests — BAL 1.0 documentation - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        tests¶

        -
        -

        __init__.py¶

        -
        -
        -

        test_all_neighb.py¶

        -

        Title: test_all_neighb.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-02 -Description: Unit testing for ALL_NEIGHB dictionary in value_lookup.py

        -
        -
        -

        test_bal_cal.py¶

        -

        Title: test_bal_cal.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-09 -Description: Unit testing module for bal_cal function in calculate_bal.py

        -
        -
        -

        test_bal_class.py¶

        -

        Title: test_bal_class.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-02 -Description: Unit testing module for BAL_CLASS dictionary in -bal_database.py

        -
        -
        -

        test_bal_esti.py¶

        -

        Title: test_bal_esti.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-02 -Description: Unit testing module for bal_esti function in calculate_bal.py

        -
        -
        -

        test_convo.py¶

        -

        Title: test_convo.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-01 -Description: Unit testing module for convo function in calculate_bal.py

        -
        -
        -

        test_dist_limit.py¶

        -

        Title: test_dist_limit.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-02 -Description: Unit testing module for DIST_LIMIT_UPSLOPE and -DIST_LIMIT_DOWNSLOPE dictionary in bal_database.py

        -
        -
        -

        test_find_common_area.py¶

        -

        Title: test_find_common_area.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-06-24 -Description: Unit testing module for find_common_area function in bal.py

        -
        -
        -

        test_find_dist_class.py¶

        -

        Title: test_find_dist_class.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-02 -Description: Unit testing for find_dist_class function in calculate_bal.py

        -
        -
        -

        test_findAOI.py¶

        -
        -
        -

        test_get_extent_mask.py¶

        -

        Title: test_get_extent_mask.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-06-24 -Description: Unit testing module for get_extent_mask function in bal.py

        -
        -
        -

        test_get_slope_aspect.py¶

        -

        Title: test_get_slope_aspect.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-06-24 -Description: Unit testing module for get_slope_aspect function in bal.py

        -
        -
        -

        test_get_slope_in_aspect.py¶

        -

        Title: test_get_slope_in_aspect.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-01 -Description: Unit testing module for get_slope_in_aspect function -in calculate_bal.py

        -
        -
        -

        tes_point_c.py¶

        -

        Title: test_point_c.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-02 -Description: Unit testing module for POINT_C dictionary in value_lookup.py

        -
        -
        -

        test_point_r.py¶

        -

        Title: test_point_r.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-02 -Description: Unit testing module for POINT_R dictionary in value_lookup.py

        -
        -
        -

        test_reclass_veg.py¶

        -

        Title: test_reclas_veg.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-06-24 -Description: Unit testing module for reclass_veg function in bal.py

        -
        -
        -

        test_scenario.py¶

        -

        Title: test_scenario.py -Author: Tina Yang, tina.yang@ga.gov.au -CreationDate: 2015-07-24 -Description: scenario test based on sample input data: classified veg, -classified slope and classified aspect.

        -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/use_limit.html b/docs/html/docs/use_limit.html deleted file mode 100644 index 2ad85ce..0000000 --- a/docs/html/docs/use_limit.html +++ /dev/null @@ -1,120 +0,0 @@ - - - - - - - - - - Introduction — BAL 1.0 documentation - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Introduction¶

        -

        Fire is a natural feature of the Australian landscape and remains an ever-present threat. Bushfire threat analysis aims to inform the fire authorities and the community of the bushfire hazard in an effort to manage the risk posed to life, property and the environment.

        -

        Bushfire attack level (BAL) is a measure of the severity of a building’s potential exposure to bushfire. It is defined in the Australian standard AS 3959 (2009)–Construction of buildings in bushfire-prone areas, to serve as a basis for establishing the requirements for construction, to improve the protection of buildings from bushfire attack. The Standard describes how to compute the bushfire attack level for any location and directly links this to recommendations on the design of existing or planned buildings.

        -

        The BAL toolbox implements the rules described by method 1 in the national standard AS 3959 (2009) by integrating them into a computational code that can be run by non-technical people in an ArcGIS environment.

        -
        -

        Package structures¶

        -

        The toolbox name is BAL.tbx that is associated with a python script bal.py to derive bushfire attack level values. The script bal.py links to a python script calculate_bal.py and a module Utilities, which includes supporting dictionaries defined in two python scripts:

        -
          -
        • value_lookup.py;
          • -
        • bal_database.py.
          • -
        -

        There are two more folders:

        -

        docs: holding the documentation files.

        -

        tests: holding the unit tests, scenario tests and their test data.

        -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/docs/utilities.html b/docs/html/docs/utilities.html deleted file mode 100644 index 92a77ae..0000000 --- a/docs/html/docs/utilities.html +++ /dev/null @@ -1,257 +0,0 @@ - - - - - - - - - - utilities — BAL 1.0 documentation - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        utilities¶

        -

        These are tools or functions used to support the main computation.

        -
        -

        __init__.py¶

        -
        -
        -

        value_lookup.py¶

        -

        value_lookup - helpful dictionaries for calculating the -bushfire attack level (BAL)

        -
        -

        These dictionaries are helpful to adapt the algorithm spatially to Method 1 -in AS 3959 (2009).

        - --- - - - -
        moduleauthor:Tina Yang <tina.yang@ga.gov.au>
        -
        -
        -

        bal_database.py¶

        -

        bal_database - relevant dictionaries for calculating the -bushfire attack level (BAL)

        -
        -

        These dictionaries are translated from tables from 2.4.2 to 2.4.5 in -AS 3959 (2009) to determine the BAL for an area of interest within Australia.

        - --- - - - -
        moduleauthor:Tina Yang <tina.yang@ga.gov.au>
        -
        -
        -

        sa_tools.py¶

        -

        sa_tools - some support functions replacing spatial analyst

        -
        -

        This module includes algorithms that are used to replace spatial analyst -functions such as ExtractByMask, Reclassify, Slope and Aspect used within this -package.

        - --- - - - -
        moduleauthor:Tina Yang <tina.yang@ga.gov.au>
        -
        -
        -sa_tools.cal_slope_aspect(dem, slope_fname, aspect_fname)[source]¶
        -

        Calculate the slope from the input dem

        - --- - - - -
        Parameters:
          -
        • dem – file the input dem
          • -
        • slope_fname – file the output slope
          • -
        • aspect_fname – file the output aspect
          • -
        -
        -
        - -
        -
        -sa_tools.clip_array(data, x_left, y_upper, pixelwidth, pixelheight, extent)[source]¶
        -

        Return the clipped area of the input array according to an sub-extent

        - --- - - - - - -
        Parameters:
          -
        • data – numpy.ndarray the input array
          • -
        • x_left – float the left-most x projected coordinate
          • -
        • y_upper – float the upper-most y projected coordinate
          • -
        • pixelwidth – float the pixel width
          • -
        • pixelheight – float the pixel height
          • -
        • extent – tuple the clipping extent
          • -
        -
        Returns:

        numpy.ndarray the clipped array

        -
        -
        - -
        -
        -sa_tools.extract_by_mask(image_fname, extent_file, out_fname)[source]¶
        -

        Extract a raster using a feature (shape) file

        - --- - - - - - -
        Parameters:
          -
        • image_fname – file the input raster
          • -
        • extent_file – file the input extent feature file
          • -
        -
        Returns:

        file the output raster

        -
        -
        - -
        -
        -sa_tools.reclassify(image_fname, remap, out_fname)[source]¶
        -

        Reclassify the raster as per the input remap

        - --- - - - - - -
        Parameters:
          -
        • image_fname – file the input raster
          • -
        • remap – str the info of remap
          • -
        -
        Returns:

        file the output raster

        -
        -
        - -
        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Previous topic

        -

        Calculate_bal

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/genindex.html b/docs/html/genindex.html deleted file mode 100644 index cf46961..0000000 --- a/docs/html/genindex.html +++ /dev/null @@ -1,339 +0,0 @@ - - - - - - - - - - - - Index — BAL 1.0 documentation - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - - -

        Index

        - -
        - _ - | B - | C - | E - | F - | G - | R - | S - | T - | V - -
        -

        _

        - - -
        - -
        __init__ (module), [1] -
        - -
        - -

        B

        - - - -
        - -
        bal (module) -
        - - -
        bal_cal() (in module calculate_bal) -
        - - -
        bal_calc() (in module bal) -
        - -
        - -
        bal_database (module) -
        - - -
        bal_esti() (in module calculate_bal) -
        - -
        - -

        C

        - - - -
        - -
        cal_slope_aspect() (in module sa_tools) -
        - - -
        calculate_bal (module) -
        - -
        - -
        clip_array() (in module sa_tools) -
        - - -
        convo() (in module calculate_bal) -
        - -
        - -

        E

        - - -
        - -
        extract_by_mask() (in module sa_tools) -
        - -
        - -

        F

        - - - -
        - -
        find_aoi() (in module bal) -
        - - -
        find_common_area() (in module bal) -
        - -
        - -
        find_dist_class() (in module calculate_bal) -
        - -
        - -

        G

        - - - -
        - -
        get_extent_mask() (in module bal) -
        - - -
        get_footprint() (in module bal) -
        - - -
        get_max_bal() (in module calculate_bal) -
        - -
        - -
        get_slope_aspect() (in module bal) -
        - - -
        get_slope_in_aspect() (in module calculate_bal) -
        - -
        - -

        R

        - - - -
        - -
        reclass_veg() (in module bal) -
        - - -
        reclassify() (in module sa_tools) -
        - -
        - -
        run() (in module bal) -
        - -
        - -

        S

        - - -
        - -
        sa_tools (module) -
        - -
        - -

        T

        - - - -
        - -
        test_all_neighb (module) -
        - - -
        test_bal_cal (module) -
        - - -
        test_bal_class (module) -
        - - -
        test_bal_esti (module) -
        - - -
        test_convo (module) -
        - - -
        test_dist_limit (module) -
        - - -
        test_find_common_area (module) -
        - - -
        test_find_dist_class (module) -
        - -
        - -
        test_get_extent_mask (module) -
        - - -
        test_get_slope_aspect (module) -
        - - -
        test_get_slope_in_aspect (module) -
        - - -
        test_point_c (module) -
        - - -
        test_point_r (module) -
        - - -
        test_reclass_veg (module) -
        - - -
        test_scenario (module) -
        - -
        - -

        V

        - - -
        - -
        value_lookup (module) -
        - -
        - - - -
        -
        -
        -
        -
        - - - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/index.html b/docs/html/index.html deleted file mode 100644 index acd431e..0000000 --- a/docs/html/index.html +++ /dev/null @@ -1,188 +0,0 @@ - - - - - - - - - - Bushfire Attack Level — BAL 1.0 documentation - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -
        -

        Bushfire Attack Level¶

        -
        -
        -

        Overview¶

        -

        This toolbox is used to compute the Bushfire Attack Level (BAL) for an area of interest within Australia based on the input vegetation and elevation datasets.

        -

        The computation algorithm is adapted spatially to Method 1 in the Australian Standard AS 3959 (2009)–Construction of buildings in bushfire-prone areas.

        -

        The output contains eight raster files that represent the BAL for each of eight cardinal directions and an extra raster file that represents the maximum BAL of the eight directions for each grid cell.

        -
        -
        -

        Disclaimer¶

        -
        - -
        -
        -
        -

        Introduction¶

        -
        - -
        -
        - -
        -

        Code documentation¶

        -

        This part is extracted from the source code in-line documentation and included in this document for the completeness of the software package. It does not directly instruct users how to use the toolbox to calculate the BAL. Instead, it might be useful for software engineers or developers to review the source code and maintain or upgrade it in the future.

        -
        - -
        -
        -
        -

        References¶

        -

        AS 3959, 2009. Construction of buildings in bushfire-prone areas, Australian Standard

        -
        - - -
        -
        -
        -
        -
        -

        Table Of Contents

        - - -

        Next topic

        -

        Disclaimer

        -

        This Page

        - - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/objects.inv b/docs/html/objects.inv deleted file mode 100644 index b0cc186..0000000 Binary files a/docs/html/objects.inv and /dev/null differ diff --git a/docs/html/py-modindex.html b/docs/html/py-modindex.html deleted file mode 100644 index 0944307..0000000 --- a/docs/html/py-modindex.html +++ /dev/null @@ -1,234 +0,0 @@ - - - - - - - - - - Python Module Index — BAL 1.0 documentation - - - - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - - -

        Python Module Index

        - -
        - _ | - b | - c | - s | - t | - v -
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
         
        - _
        - __init__ -
         
        - b
        - bal -
        - bal_database -
         
        - c
        - calculate_bal -
         
        - s
        - sa_tools -
         
        - t
        - test_all_neighb -
        - test_bal_cal -
        - test_bal_class -
        - test_bal_esti -
        - test_convo -
        - test_dist_limit -
        - test_find_common_area -
        - test_find_dist_class -
        - test_get_extent_mask -
        - test_get_slope_aspect -
        - test_get_slope_in_aspect -
        - test_point_c -
        - test_point_r -
        - test_reclass_veg -
        - test_scenario -
         
        - v
        - value_lookup -
        - - -
        -
        -
        -
        -
        - - -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/search.html b/docs/html/search.html deleted file mode 100644 index 3aec908..0000000 --- a/docs/html/search.html +++ /dev/null @@ -1,105 +0,0 @@ - - - - - - - - - - Search — BAL 1.0 documentation - - - - - - - - - - - - - - - -
        -

        Navigation

        - -
        - -
        -
        -
        -
        - -

        Search

        -
        - -

        - Please activate JavaScript to enable the search - functionality. -

        -
        -

        - From here you can search these documents. Enter your search - words into the box below and click "search". Note that the search - function will automatically search for all of the words. Pages - containing fewer words won't appear in the result list. -

        -
        - - - -
        - -
        - -
        - -
        -
        -
        -
        -
        -
        -
        -
        -
        -
        -

        Navigation

        - -
        -
        - © Copyright 2015, Geoscience Australia. - Created using Sphinx 1.1.3. -
        - - \ No newline at end of file diff --git a/docs/html/searchindex.js b/docs/html/searchindex.js deleted file mode 100644 index 0546bcb..0000000 --- a/docs/html/searchindex.js +++ /dev/null @@ -1 +0,0 @@ -Search.setIndex({objects:{"":{test_dist_limit:[9,0,1,""],value_lookup:[7,0,1,""],calculate_bal:[5,0,1,""],test_bal_esti:[9,0,1,""],test_find_common_area:[9,0,1,""],test_scenario:[9,0,1,""],test_all_neighb:[9,0,1,""],test_reclass_veg:[9,0,1,""],test_find_dist_class:[9,0,1,""],sa_tools:[7,0,1,""],test_get_extent_mask:[9,0,1,""],"__init__":[7,0,1,""],bal_database:[7,0,1,""],test_point_r:[9,0,1,""],test_get_slope_aspect:[9,0,1,""],bal:[3,0,1,""],test_point_c:[9,0,1,""],test_get_slope_in_aspect:[9,0,1,""],test_bal_cal:[9,0,1,""],test_convo:[9,0,1,""],test_bal_class:[9,0,1,""]},calculate_bal:{get_slope_in_aspect:[5,1,1,""],convo:[5,1,1,""],find_dist_class:[5,1,1,""],get_max_bal:[5,1,1,""],bal_esti:[5,1,1,""],bal_cal:[5,1,1,""]},bal:{find_common_area:[3,1,1,""],bal_calc:[3,1,1,""],run:[3,1,1,""],reclass_veg:[3,1,1,""],get_slope_aspect:[3,1,1,""],find_aoi:[3,1,1,""],get_extent_mask:[3,1,1,""],get_footprint:[3,1,1,""]},sa_tools:{clip_array:[7,1,1,""],reclassify:[7,1,1,""],extract_by_mask:[7,1,1,""],cal_slope_aspect:[7,1,1,""]}},terms:{all:[1,2,5,8,10,11],code:[0,8,2],dist:5,consider:11,four:1,landscap:8,follow:[8,6],row:5,content:2,decid:5,accur:[8,4],depend:2,zone:[11,1],sensit:8,effort:8,moorland:[10,11,1],veg:[3,9,5],decis:4,image_fnam:7,under:[10,11],calculate_b:[0,8,9,5],test_get_slope_aspect:9,southwest:11,merchant:4,digit:8,sourc:[0,7,2,5,3],string:[10,5],disclos:4,veg_data:5,illawarra:1,util:[0,7,8],govern:4,relev:[7,11],tri:4,level:[0,7,8,5,3],button:10,cmd:2,list:[11,5],geograph:1,refer:[0,1,4,8,3],pleas:[8,2],upper:[7,5],impli:4,natur:8,direct:[0,11,1,5],shrubland:[10,11,1],second:8,design:8,further:11,click:[10,1,6],compat:2,index:1,sub:7,currenc:8,cell:[0,11,8],"\u03b2":[1,6],run:[0,1,2,3,8,10],"new":[1,6],ever:8,method:[0,3,5,7,8,11],can:[8,11,1,2],full:1,deriv:[10,3,11,8,4],gener:1,privat:4,here:[1,2],disclaim:[0,4],test_bal_esti:9,calcuat:3,path:[10,1,2],get_footprint:3,valu:[1,3,4,5,8,10,11],box:6,test_point_c:9,test_point_r:9,opinion:4,chang:[1,2],test_get_slope_in_aspect:9,danger:1,appli:11,modul:[3,7,8,9,5],prefer:[8,2],seven:[11,1],alpin:1,instal:[0,1,2],total:[8,4],establish:8,unit:[8,1,2,9],reproject:1,test_bal_c:9,from:[0,1,2,3,4,5,7,8,11],describ:[10,8],would:4,commun:8,arcgi:[8,1,2,6],two:8,coverag:[8,1],reclassif:[10,3,1],call:6,recommend:[8,2,4],find_dist_class:[9,5],australian:[0,1,3,4,5,8,11],type:[11,5],more:[8,11,1],flat:11,capit:1,bal_calc:3,test_reclas_veg:9,slope_fnam:7,line:0,customis:3,particular:4,hold:8,gda94:1,work:[2,4],uniqu:1,remain:8,nine:10,dem:[10,3,7,1,8],purpos:4,employe:4,test_dist_limit:9,give:1,process:[10,2,4],indic:4,critic:8,unzip:2,cardin:[0,11,1],risk:8,anoth:8,aspect_valu:5,classifi:[3,11,9,5],how:[0,8],forest:[10,11,1],pixelwidth:7,instead:[0,8],downslop:[11,8],map:[10,3,1],product:4,dialog:6,after:10,southern:1,aoi:3,reflect:4,befor:2,mai:[8,2],data:[1,5,7,8,9,10],circumst:[11,8],github:10,essenti:5,exclud:1,issu:2,inform:[8,1,4],maintain:0,combin:5,incorpor:8,enter:1,oper:2,help:7,endors:4,fall:11,trade:4,all_neighb:9,paramet:[10,3,7,1,5],creationd:9,fit:4,geoscienc:[8,4],window:[10,1,2,6],pythonpath:2,value_lookup:[0,7,8,9],therefor:[8,4],might:0,pixel:[7,5],finer:8,them:[11,8],within:[0,1,2,3,7,10,11],"return":[3,7,5],greater:[11,1],thei:1,python:[8,2],hunter:1,nation:8,"break":11,test_get_extent_mask:9,discuss:2,nor:4,introduct:[0,8],warranti:4,name:[10,8,1,4],run_test_al:2,weather:1,each:[0,11,1,2,5],found:1,metr:[8,11,1,5],replac:7,individu:2,remap:[10,3,7],procedur:11,expect:2,beyond:11,extract:[0,7,2],variabl:2,gradient:11,categori:[3,11],upslop:11,adapt:[0,7,8],reader:8,gov:[3,7,9,5],integr:[8,2],reclassifi:[3,7,11,1],linear:1,navig:6,output_fold:3,differ:2,standard:[0,1,3,5,8,10,11],base:[0,1,2,3,5,8,9,11],out_fnam:7,dictionari:[7,8,9],get_max_b:5,basi:8,raster:[10,0,7,1,3],a_dir:5,length:1,threat:8,rainforest:[10,11,1],nodata:10,assign:11,south:[11,1],bal_esti:[9,5],origin:[10,3],bal_databas:[0,7,8,9,5],rang:1,directli:[0,8],arrai:[7,5],independ:2,qualiti:8,number:[11,1,5],restrict:1,suitabl:1,instruct:[0,2],open:[1,6],test_find_dist_class:9,given:[11,2],district:1,script:[8,1,2],associ:8,top:6,system:[1,2],construct:[0,11,8,5,3],veget:[0,1,3,5,8,10,11],attack:[0,7,8,5,3],necessarili:4,bal_class:9,"final":11,store:[1,2],prone:[0,11,8,5,3],option:1,tool:[8,7,1,2],specifi:1,part:[0,1,5],western:[11,1],qld:1,than:[11,8],serv:8,exposur:8,target:10,provid:8,structur:8,horizont:5,project:[3,7,1],jerram_dem:10,str:[3,7],pre:2,"function":[7,9],comput:[0,7,1,2,8],clip:7,test_find_common_area:9,ani:[8,4],packag:[0,7,8,2,6],have:[1,2],tabl:[3,7,11,5],infring:4,element:2,extractbymask:7,engin:0,accuraci:4,note:1,ideal:8,build:[0,11,8,5,3],which:[8,11,1],test_scenario:9,environ:[8,2],singl:11,bal_cal:[9,5],simplifi:[11,8],shoalhaven:1,thi:[0,1,2,3,4,5,7,8,10,11],shall:4,compress:2,victoria:1,most:[7,1],eight:[0,11,1],plan:8,"class":[10,11,1,5],doc:8,adopt:[11,8],doe:[0,8,4],yang:[3,7,9,5],bal_list:5,determin:[7,11,5],grassland:[10,11,1],left:7,apparatu:4,width:[7,5],slope:[3,7,11,9,5],find:[3,6,5],test_convo:9,involv:11,onli:[2,4],northeast:11,locat:[1,2,6,8,10,11],northern:1,state:4,should:[8,1,2,4],manufactur:4,version:2,folder:[10,3,1,2,8],analys:[11,8],tbx:[8,6],mga:[10,1],get:5,familiar:8,express:4,coast:1,"import":2,report:10,toolbox:[0,1,2,6,4,8],requir:[8,1,2],enabl:2,fdi:[10,3,11,1,5],common:3,contain:[0,2],bal:[0,1,2,3,4,5,6,7,8,9,10,11],where:[8,11,1,2],view:4,set:[0,2,6],arctoolbox:6,cal_slope_aspect:7,displai:10,see:[10,1,2,6],arc:8,result:8,respons:4,fail:1,simpl:2,best:8,subject:11,review:0,below:6,favor:4,figur:[10,1,6],x_left:7,progress:10,neither:4,altern:8,accord:[7,11,1,5],dist_limit_downslop:9,kei:8,sole:[8,4],southeast:11,extent:[10,3,7,1],advertis:4,assess:5,popul:10,both:2,protect:8,img:10,howev:[8,2,4],equat:8,"__init__":[0,7,9],mani:10,col:5,jerram_veg:10,among:11,point:5,overview:0,pop:10,height:7,poi:5,respect:11,pixelheight:7,guid:4,assum:[8,4],extent_fil:7,liabil:4,west:11,territori:1,numpi:[7,2,5],three:8,been:[8,2],coars:8,interpret:11,interest:[0,1,3,5,7,8,11],basic:2,addit:1,life:8,fire:[8,11,1],resolut:[10,8,1],tes_point_c:9,neighbour:[11,5],coordin:[7,1],understand:[8,2],present:8,main:[7,2],look:10,servic:4,properti:8,convo:[9,5],commerci:4,aim:8,defin:[10,8,11,1,5],calcul:[0,1,3,5,7,10,11],abov:10,input_dem:3,malle:[10,11,1],deliv:2,herein:4,need:[1,2],limit:[8,11,1,5],sever:[8,2],develop:[0,8,2],author:[8,4,9],make:4,woodland:[10,11,1],same:[11,1],binari:2,northwest:11,document:[0,8,2,4],complet:[0,8,2,4],finish:10,charact:1,get_slope_aspect:[3,9],effect:[3,11],test_bal_class:9,y_upper:7,user:[0,1,4],improv:8,footprint:3,implement:8,appropri:[11,5],scenario:[8,9],thu:11,exampl:[0,1,2,6,8,10,11],elev:[0,8,3],hazard:8,grid:[10,0,1,8],model:8,usual:8,distanc:[11,5],wale:1,get_slope_in_aspect:[9,5],obtain:2,gda:10,shape:7,aspect:[3,7,11,9,5],tussock:[10,11,1],point_c:9,bit:2,aspect_fnam:7,sydnei:1,extra:0,param:[],add:6,input:[0,1,3,5,7,8,9,10,11],east:11,approxim:8,applic:1,australia:[0,1,3,4,7,8,10,11],format:[10,1],five:11,background:[0,11],bushfir:[0,3,5,7,8,11],measur:8,like:10,specif:[1,4,5],necessari:2,point_r:9,choic:1,upgrad:0,output:[0,1,3,5,7,8,10],manag:8,right:[4,6],convei:4,find_aoi:3,some:[7,2],sampl:[1,9],guarante:[8,4],successfulli:10,constitut:4,librari:2,distribut:2,scale:8,lead:[8,2],per:[3,7,5],test_reclass_veg:9,select:[10,11,1,6],esri:[10,8,1],pixel_width:5,either:1,sensibl:8,aspect_data:5,pose:8,step:[11,6],get_extent_mask:[3,9],about:1,zip:2,column:5,alber:10,degre:[11,8,5],srt:3,act:1,softwar:[0,8,2],produc:[10,3,1,4,8],mulga:[10,11,1],compil:2,own:[1,4],reclass_veg:[3,9],slope_data:5,arcpi:2,"float":[7,5],dataset:[0,1,3,8,10,11],down:11,extract_by_mask:7,trademark:4,ensur:2,your:2,nsw:1,find_common_area:[3,9],wai:2,area:[0,1,3,5,7,8,11],support:[7,8],avail:8,start:10,reli:[8,4],includ:[0,7,8,2,5],suit:[1,2],treat:11,analysi:8,north:11,tina:[3,7,9,5],tupl:7,regard:[11,5],test_all_neighb:9,test_findaoi:9,link:[8,2],translat:7,tasmania:1,analyst:7,info:7,consist:1,possibl:4,"default":[10,1],bal_max:10,maximum:[10,0,11,1,5],inaccur:8,those:[1,4],site:[11,8],otherwis:[11,4],featur:[7,8],constant:[11,8],"int":[3,5],descript:[8,9],clip_arrai:7,doesn:11,repres:[0,11,1,4],dist_limit:5,exist:8,file:[0,1,2,3,5,7,8,10],pip:2,sa_tool:[0,7],moduleauthor:[3,7,5],veg_class:[3,5],titl:9,when:[10,8,11,1,4],detail:[8,2],intend:[8,2],field:10,futur:0,spatial:[0,7,1,8],test:[8,1,2,9],you:[8,1,2,6],jerramungup:10,scrub:[10,11,1],flawlessli:2,ndarrai:[7,5],dist_limit_upslop:9,consid:[11,8],queensland:1,land:[11,8],algorithm:[0,7,11,8,5],directori:2,mask:3,rule:8,potenti:8,time:8,far:1},objtypes:{"0":"py:module","1":"py:function"},titles:["Bushfire Attack Level","Running the tool","Installation","Bushfire Attack Level","Disclaimer","Calculate_bal","Setting up the toolbox","utilities","Introduction","tests","An Example","Background"],objnames:{"0":["py","module","Python module"],"1":["py","function","Python function"]},filenames:["index","docs/execution","docs/install","docs/bal","docs/disclaim","docs/calculate_bal","docs/setup","docs/utilities","docs/intro","docs/tests","docs/examples","docs/background"]}) \ No newline at end of file diff --git a/docs/images/001_arcgis_folder_icon.png b/docs/images/001_arcgis_folder_icon.png new file mode 100644 index 0000000..cc1b7c0 Binary files /dev/null and b/docs/images/001_arcgis_folder_icon.png differ diff --git a/docs/images/001_bal_calculation_log.png b/docs/images/001_bal_calculation_log.png new file mode 100644 index 0000000..054e25c Binary files /dev/null and b/docs/images/001_bal_calculation_log.png differ diff --git a/docs/images/001_bal_calculation_progress.png b/docs/images/001_bal_calculation_progress.png new file mode 100644 index 0000000..1603c34 Binary files /dev/null and b/docs/images/001_bal_calculation_progress.png differ diff --git a/docs/images/001_bal_dialog_window.png b/docs/images/001_bal_dialog_window.png new file mode 100644 index 0000000..9484c00 Binary files /dev/null and b/docs/images/001_bal_dialog_window.png differ diff --git a/docs/images/001_bal_effective_slope.png b/docs/images/001_bal_effective_slope.png new file mode 100644 index 0000000..b5575a8 Binary files /dev/null and b/docs/images/001_bal_effective_slope.png differ diff --git a/docs/images/001_bal_extent_default.png b/docs/images/001_bal_extent_default.png new file mode 100644 index 0000000..b3d0565 Binary files /dev/null and b/docs/images/001_bal_extent_default.png differ diff --git a/docs/images/001_bal_extent_options.png b/docs/images/001_bal_extent_options.png new file mode 100644 index 0000000..c8f0b01 Binary files /dev/null and b/docs/images/001_bal_extent_options.png differ diff --git a/docs/images/001_bal_fdi_value.png b/docs/images/001_bal_fdi_value.png new file mode 100644 index 0000000..b4c9f2c Binary files /dev/null and b/docs/images/001_bal_fdi_value.png differ diff --git a/docs/images/001_bal_input_dem.png b/docs/images/001_bal_input_dem.png new file mode 100644 index 0000000..89d911c Binary files /dev/null and b/docs/images/001_bal_input_dem.png differ diff --git a/docs/images/001_bal_input_vegetation.png b/docs/images/001_bal_input_vegetation.png new file mode 100644 index 0000000..d20fd73 Binary files /dev/null and b/docs/images/001_bal_input_vegetation.png differ diff --git a/docs/images/001_bal_input_vegetation_classification.png b/docs/images/001_bal_input_vegetation_classification.png new file mode 100644 index 0000000..e3e8b3d Binary files /dev/null and b/docs/images/001_bal_input_vegetation_classification.png differ diff --git a/docs/images/001_bal_levels_flat.png b/docs/images/001_bal_levels_flat.png new file mode 100644 index 0000000..392afb3 Binary files /dev/null and b/docs/images/001_bal_levels_flat.png differ diff --git a/docs/images/001_bal_method1_workflow.png b/docs/images/001_bal_method1_workflow.png new file mode 100644 index 0000000..9567067 Binary files /dev/null and b/docs/images/001_bal_method1_workflow.png differ diff --git a/docs/images/001_bal_output_path.png b/docs/images/001_bal_output_path.png new file mode 100644 index 0000000..8743696 Binary files /dev/null and b/docs/images/001_bal_output_path.png differ diff --git a/docs/images/001_bal_toolbox_help.png b/docs/images/001_bal_toolbox_help.png new file mode 100644 index 0000000..7b580e7 Binary files /dev/null and b/docs/images/001_bal_toolbox_help.png differ diff --git a/docs/images/001_bal_unittest_complete.png b/docs/images/001_bal_unittest_complete.png new file mode 100644 index 0000000..d09f1a9 Binary files /dev/null and b/docs/images/001_bal_unittest_complete.png differ diff --git a/docs/images/001_bal_unittest_execution.png b/docs/images/001_bal_unittest_execution.png new file mode 100644 index 0000000..0ce157f Binary files /dev/null and b/docs/images/001_bal_unittest_execution.png differ diff --git a/docs/images/001_bal_vegetation_distance.png b/docs/images/001_bal_vegetation_distance.png new file mode 100644 index 0000000..cf0cca8 Binary files /dev/null and b/docs/images/001_bal_vegetation_distance.png differ diff --git a/docs/images/001_bushfire_crc_logo.jpg b/docs/images/001_bushfire_crc_logo.jpg new file mode 100644 index 0000000..da0f377 Binary files /dev/null and b/docs/images/001_bushfire_crc_logo.jpg differ diff --git a/docs/images/001_dfes_logo.jpg b/docs/images/001_dfes_logo.jpg new file mode 100644 index 0000000..2acb6b7 Binary files /dev/null and b/docs/images/001_dfes_logo.jpg differ diff --git a/docs/images/001_ga_community_safety.png b/docs/images/001_ga_community_safety.png new file mode 100644 index 0000000..36c9a97 Binary files /dev/null and b/docs/images/001_ga_community_safety.png differ diff --git a/docs/BAL_calculation_window.jpg b/docs/images/BAL_calculation_window.jpg similarity index 100% rename from docs/BAL_calculation_window.jpg rename to docs/images/BAL_calculation_window.jpg diff --git a/docs/BAL_output.jpg b/docs/images/BAL_output.jpg similarity index 100% rename from docs/BAL_output.jpg rename to docs/images/BAL_output.jpg diff --git a/docs/images/BAL_table.JPG b/docs/images/BAL_table.JPG new file mode 100644 index 0000000..14f63b7 Binary files /dev/null and b/docs/images/BAL_table.JPG differ diff --git a/docs/BAL_toolbox.jpg b/docs/images/BAL_toolbox.jpg similarity index 100% rename from docs/BAL_toolbox.jpg rename to docs/images/BAL_toolbox.jpg diff --git a/docs/images/Bal_max.jpg b/docs/images/Bal_max.jpg new file mode 100644 index 0000000..4d495f0 Binary files /dev/null and b/docs/images/Bal_max.jpg differ diff --git a/docs/images/Slope_determination.JPG b/docs/images/Slope_determination.JPG new file mode 100644 index 0000000..e381e65 Binary files /dev/null and b/docs/images/Slope_determination.JPG differ diff --git a/docs/addtoolbox_dialog.jpg b/docs/images/addtoolbox_dialog.jpg similarity index 100% rename from docs/addtoolbox_dialog.jpg rename to docs/images/addtoolbox_dialog.jpg diff --git a/docs/arctoolbox.jpg b/docs/images/arctoolbox.jpg similarity index 100% rename from docs/arctoolbox.jpg rename to docs/images/arctoolbox.jpg diff --git a/docs/dem_example.jpg b/docs/images/dem_example.jpg similarity index 100% rename from docs/dem_example.jpg rename to docs/images/dem_example.jpg diff --git a/docs/example_BAL_calculation.jpg b/docs/images/example_BAL_calculation.jpg similarity index 100% rename from docs/example_BAL_calculation.jpg rename to docs/images/example_BAL_calculation.jpg diff --git a/docs/example_process.jpg b/docs/images/example_process.jpg similarity index 100% rename from docs/example_process.jpg rename to docs/images/example_process.jpg diff --git a/docs/images/geoscience_inline.jpg b/docs/images/geoscience_inline.jpg new file mode 100644 index 0000000..dc78abe Binary files /dev/null and b/docs/images/geoscience_inline.jpg differ diff --git a/docs/html/_images/rightclick_arctoolbox.jpg b/docs/images/rightclick_arctoolbox.jpg similarity index 100% rename from docs/html/_images/rightclick_arctoolbox.jpg rename to docs/images/rightclick_arctoolbox.jpg diff --git a/docs/html/_images/select_bal.jpg b/docs/images/select_bal.jpg similarity index 100% rename from docs/html/_images/select_bal.jpg rename to docs/images/select_bal.jpg diff --git a/docs/html/_images/veg_example.jpg b/docs/images/veg_example.jpg similarity index 100% rename from docs/html/_images/veg_example.jpg rename to docs/images/veg_example.jpg diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..5913fe4 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,36 @@ +.. Bushfire Attack Level Toolbox documentation master file, created by + sphinx-quickstart on Wed Apr 12 11:02:21 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Bushfire Attack Level Toolbox's documentation! +========================================================= + +Overview +-------- + +This toolbox is used to compute the Bushfire Attack Level (BAL) for an +area of interest within Australia based on the input vegetation and +elevation datasets. + +The computation algorithm is adapted spatially to Method 1 in the +Australian Standard AS 3959 (2009)--*Construction of buildings in +bushfire-prone areas*. + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + disclaim + userguide/index + training/index + + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 4c21acd..0000000 --- a/docs/install.rst +++ /dev/null @@ -1,45 +0,0 @@ -Installation -============ - -Installing BAL Toolbox is intended to be a simple process, requiring only basic understanding of ArcGIS toolbox operations. It has been installed and tested on ArcGIS 10.2. - - -Unzipping the toolbox ---------------------- - -The software package is delivered as a compressed zip file. Unzip the toolbox into a location on your computer, for example C:\\bal. Then you will have stored all the files at folder C:\\bal. - - -Dependencies ------------- - -This toolbox is developed and tested within ArcGIS 10.2 that integrates with Python 2.7 and Numpy 1.6.2. It is not recommended to install an independent version of Python for use in ArcGIS. Using a different version of Python may lead to compatibility issues. - -However, if necessary, there are several ways to obtain the required libraries -- using Python's recommended tool `pip -`_, installing a distribution such as `Python(x,y) package `_ (for Windows environments), or installing the libraries from source or binary installers (pre-compiled binary Windows installer versions for all the libraries (both 32-bit and 64-bit) can be obtained `here `_). - -For detailed instructions on installation of these dependencies, please see the documentation for each individual library. - -* `Python `_ - v2.7 preferred -* `Numpy `_ - v1.6.2 preferred -* `Nose `_ -* `Arcpy in ArcGIS 10.2 `_ - -.. note:: ArcGIS 10.2 is packaged with a modified version of `Numpy`. In our experience, attempting to update the `Numpy` package will cause the `arcpy` library to fail catastrophically, and usually without reporting any error message. We recommend not trying to upgrade the version of `Numpy` linked to your `ArcGIS` installation. - -Setting the environment ------------------------ -To enable BAL toolbox to run flawlessly, you may need to change some environment settings. The important variable to set is the ``PYTHONPATH`` variable. This should be set to the path where you have extracted the contents of the zip file. A complete discussion on environment variables in Python is given in the `Python documentation `_. - -Windows -~~~~~~~ -The Python documentation contains some simple instructions for setting environment variables on Windows systems `here `_. See `this link `_ for setting the variables on different Windows systems. - -Testing the installation ------------------------- - -The code includes a suite of unit tests that ensure elements of the code base work as expected. The code should be tested before running the toolbox. Users will need to install the `Nose `_ package to run these tests. - -The test suite can be run from the main directory. On Windows, run the ``run_test_all.cmd`` script from the main BAL directory. - - diff --git a/docs/intro.rst b/docs/intro.rst deleted file mode 100644 index f6f6651..0000000 --- a/docs/intro.rst +++ /dev/null @@ -1,45 +0,0 @@ -Introduction -============ - -Fire is a natural feature of the Australian landscape and remains an ever-present threat. Bushfire threat analysis aims to inform the fire authorities and the community of the bushfire hazard in an effort to manage the risk posed to life, property and the environment. - -Bushfire Attack Level (BAL) is a measure of the severity of a building's potential exposure to bushfire. It is defined in the Australian Standard AS 3959 (2009)--*Construction of buildings in bushfire-prone areas*, to serve as a basis for establishing the requirements for construction, to improve the protection of buildings from bushfire attack. The Standard describes how to compute the bushfire attack level for any location and directly links this to recommendations on the design of existing or planned buildings. - -The BAL toolbox implements the rules described by Method 1 in AS 3959 (2009) by integrating them into a computational code that can be run in the ESRI ArcGIS 10.2 environment. - - -Package structures ------------------- - -The toolbox name is **BAL.tbx**. This toolbox is associated with a python script, **bal.py**, to derive BAL. The script **bal.py** links to a python script **calculate_bal.py** and a module **Utilities**, which includes supporting dictionaries defined in two python scripts: - -* value_lookup.py; -* bal_database.py. - -There are three more folders: - -* **docs**: holding the documentation files. - -* **tests**: holding the unit tests, scenario tests and their test data. - -* **examples**: holding the example input and output data. - - -Use limitations ---------------- - -The BAL tool developed in Geoscience Australia (GA) has been developed and tested in ArcGIS 10.2. However, GA does not guarantee that the information derived is totally accurate or complete. Therefore, you should not solely rely on this information. Key limitations/approximations include the following: - -* The BAL is produced based on the simplified method (Method 1) in AS 3959 (2009). When the land downslope is more than 20 degrees, more detailed method (Method 2) should be adopted. Method 2 has not been incorporated into the toolbox developed. Instead, a constant value of 200 is provided as BAL for such circumstances. - -* Elevation data is a critical input of the tool. Digital Elevation Model (DEM) with finer resolution usually leads to more accurate BAL results. The example data uses a DEM with a resolution of 1 second of arc (approximate 30 m by 30 m grid cell at the equator), the best available national scale elevation dataset at the time of modelling. As with all spatial analyses, the results are sensitive to the input DEM's quality, resolution, coverage and currency and should therefore be used with this understanding. - -* Vegetation data is another critical input into the tool. Method 1 in AS 3959 (2009) considers the vegetation up to 100 metres from the site of interest. Ideally the vegetation with finer resolution (preferred at metre level) is required to derive sensible BAL analyses. Where finer vegetation data is not available, the alternative coarse vegetation data may lead to inaccurate output BAL. - -* The BAL toolbox is intended to run in the ArcGIS toolbox environment and is not intended to run in a Python script environment. - -* This software algorithm adapts to the Method 1 in AS 3959 (2009) by modelling it spatially. Readers are assumed to be familiar with AS 3959 (2009). For the detailed description of the Method 1, please refer to the Standard AS 3959 (2009). - - - - diff --git a/docs/rightclick_arctoolbox.jpg b/docs/rightclick_arctoolbox.jpg deleted file mode 100644 index a05e766..0000000 Binary files a/docs/rightclick_arctoolbox.jpg and /dev/null differ diff --git a/docs/select_bal.jpg b/docs/select_bal.jpg deleted file mode 100644 index 6d1883e..0000000 Binary files a/docs/select_bal.jpg and /dev/null differ diff --git a/docs/setup.rst b/docs/setup.rst deleted file mode 100644 index ac0e3e7..0000000 --- a/docs/setup.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. |beta| unicode:: U+003B2 .. GREEK SMALL LETTER BETA - -.. _setup: - -====================== -Setting up the toolbox -====================== - -Adding the toolbox into ArcGIS 10.2 ------------------------------------ - -Follow the steps below to add the toolbox into ArcGIS 10.2: - -* Open the ArcToolBox window. See Figure 4.1. - -.. figure:: arctoolbox.jpg - :align: center - :alt: ArcToolbox window. - :figclass: align-center - - The ArcToolbox window. - -* Right click **ArcToolbox** at the top of the window, see Figure 4.2. - -.. figure:: rightclick_arctoolbox.jpg - :align: center - :alt: Right click ArcToolbox in the ArcToolbox window. - :figclass: align-center - - Right click **ArcToolbox** in the ArcToolbox window. - -* Select **Add Toolbox...**, a dialog box is open. See Figure 4.3. - -.. figure:: addtoolbox_dialog.jpg - :align: center - :alt: addtoolbox dialog window. - :figclass: align-center - - The **Add Toolbox** dialog window. - -* In the dialog box, navigate to the location of the package, for example C:\\bal, you will find the **BAL.tbx**. See Figure 4.3. - - -* Select **BAL.tbx** and click **Open**, a new toolbox called **BAL** is added to the ArcToolbox. See Figure 4.4. - -.. figure:: BAL_toolbox.jpg - :align: center - :alt: Bal toolbox is added. - :figclass: align-center - - The **Bal** toolbox is added. - - diff --git a/docs/tests.rst b/docs/tests.rst deleted file mode 100644 index 6ce5e46..0000000 --- a/docs/tests.rst +++ /dev/null @@ -1,149 +0,0 @@ - -tests -********************** - -__init__.py -=========================================== - - -.. automodule:: __init__ - :members: - - - -test_all_neighb.py -=========================================== - - -.. automodule:: test_all_neighb - :members: - - -test_bal_cal.py -=========================================== - - -.. automodule:: test_bal_cal - :members: - - -test_bal_class.py -=========================================== - - -.. automodule:: test_bal_class - :members: - - - -test_bal_esti.py -=========================================== - - -.. automodule:: test_bal_esti - :members: - - - -test_convo.py -=========================================== - - -.. automodule:: test_convo - :members: - - -test_dist_limit.py -=========================================== - - -.. automodule:: test_dist_limit - :members: - - - -test_find_common_area.py -=========================================== - - -.. automodule:: test_find_common_area - :members: - - - -test_find_dist_class.py -=========================================== - - -.. automodule:: test_find_dist_class - :members: - - -test_findAOI.py -=========================================== - - -.. automodule:: test_findAOI - :members: - - - -test_get_extent_mask.py -=========================================== - - -.. automodule:: test_get_extent_mask - :members: - - - -test_get_slope_aspect.py -=========================================== - - -.. automodule:: test_get_slope_aspect - :members: - - - -test_get_slope_in_aspect.py -=========================================== - - -.. automodule:: test_get_slope_in_aspect - :members: - - - -tes_point_c.py -=========================================== - - -.. automodule:: test_point_c - :members: - - -test_point_r.py -=========================================== - - -.. automodule:: test_point_r - :members: - - -test_reclass_veg.py -=========================================== - - -.. automodule:: test_reclass_veg - :members: - - - -test_scenario.py -=========================================== - - -.. automodule:: test_scenario - :members: - diff --git a/docs/training/agenda.rst b/docs/training/agenda.rst new file mode 100644 index 0000000..964ab77 --- /dev/null +++ b/docs/training/agenda.rst @@ -0,0 +1,17 @@ +.. _agenda: + +Workshop agenda +=============== + +The |project_name| training workshop is facilitated by |GA|, supported by |DFES|. + +* Welcome +* Background +* Introduction to |project_name| +* Installing the Toolbox +* Executing an analysis +* Extracting BAL values +* Recap + + + diff --git a/docs/training/bal.rst b/docs/training/bal.rst new file mode 100644 index 0000000..c997be7 --- /dev/null +++ b/docs/training/bal.rst @@ -0,0 +1,261 @@ +.. _whatisbal: + +What is the Bushfire Attack Level +================================= + +The Bushfire Attack Level measures the **severity of a building's +potential exposure** to ember attack, radiant heat and direct flame +contact. It is intended to improve the resistance of buildings to +bushfire attack from burning embers, radiant heat, flame contact or a +combination of these. It applies to buildings sited in designated +bushfire-prone areas, as defined in the National Construction Code, Volume 2 +[NCCV2]_. + +By improving the ability of buildings in bushfire-prone areas to +withstand attack from bushfire, there is an increase in the protection +afforded to building occupants (until the fire front passes) as well +as to the building itself. + +However, improving the design and construction of buildings is only +one way that property owners can address the damage during a +bushfire. Other measures fall within the areas of planning, +subdivision, siting, landscaping and maintenance. + +.. note:: It should be borne in mind that the measures contained in + this Standard cannot guarantee that a building will survive + a bushfire event on every occasion. This is substantially + due to the degree of vegetation management, the + unpredictable nature and behaviour of fire, and extreme + weather conditions (AS 3959--2009). + +The bushfire attack level is a measure of the severity of a building's +potential exposure to ember attack, radiant heat and direct flame +contact, using increments of radiant heat expressed in kilowatts per +metre squared. When calculated, the |project_name| toolbox provides +classified levels: + +* BAL--LOW +* BAL--12.5 +* BAL--19 +* BAL--29 +* BAL--40 +* BAL--FZ + +Appendix G in AS 3959--2009 describes the threats associated with each BAL. + +.. determinebal: + +How do we determine BAL +======================= + +The |project_name| toolbox applies Method 1 from AS 3959--2009 to +determine the BAL. Method 1 is a simplified procedure to determine the +BAL, which involves five steps. This method is subject to limitations +on the circumstances in which it can be used. + +.. warning:: This method is not valid where the effective slope under + the classified vegetation is more than 20 degrees + downslope. Within the BAL toolbox, where the slope is + greater than 20 degrees, a constant value of 200 is + assigned to the BAL. + +There are five steps in determining the BAL based on method 1 in AS 3959--2009. + +Step 1: Determine the relevant FDI + +Step 2: Determine the classified vegetation type(s) + +Step 3: Determine the distance of the site from the classified +vegetation type(s) + +Step 4: Determine the effective slope(s) under the classified +vegetation type(s) + +Step 5: Determine the BAL from the appropriate table + +.. note:: AS 3959-2009 includes a sixth step, which refers to + construction requirements. This is not of interest in the + BAL toolbox, so is omitted here. + +The following sections provide details on determining the BAL, using +|project_name|. + +Determine relevant FDI +---------------------- + +The relevant Fire Danger Index (FDI) is based on Table 2.1 from AS +3959--2009, for each jurisdiction or region within a jurisdiction. The +FDI is an indication of the chance of a fire starting, its rate of +spread, intensity and the difficulty of suppresion based on the +combination of air temperature, relative humidity, wind speed and both +long- and short-term drought effects. The FDI used in AS 3959--2009 +refers to the Forest Fire Danger Index calculated by the McArthur Mk 5 +Forest Fire Danger Meter using the equations published by Noble *et +al.* (1980) [1]_. + +.. table:: Jurisdictional and regional values for FDI (adapted from + Table 2.1, `AS 3959, 2009 + `_). + :widths: 50, 10 + + +----------------------------------------------------+---------+ + | **State/region** | FDI | + +----------------------------------------------------+---------+ + | **Australian Capital Territory** | 100 | + +----------------------------------------------------+---------+ + | **New South Wales** | - | + +----------------------------------------------------+---------+ + | (a) Greater Hunter, Greater Sydney, | | + | Illawarra/Shoalhaven, Far South Coast, | 100 | + | | | + | and Southern Ranges fire weather districts | | + +----------------------------------------------------+---------+ + | (b) NSW alpine areas | 50 | + +----------------------------------------------------+---------+ + | (c) NSW general (excluding alpine areas, Greater | | + | Hunter, Greater Sydney, | | + | | 80 | + | Illawarra/Shoalhaven,Far South Coast and | | + | Southern Ranges fire weather districts) | | + +----------------------------------------------------+---------+ + | **Northern Territory** | 40 | + +----------------------------------------------------+---------+ + | **Queensland** | 40 | + +----------------------------------------------------+---------+ + | **South Australia** | 80 | + +----------------------------------------------------+---------+ + | **Tasmania** | 50 | + +----------------------------------------------------+---------+ + | **Victoria** | - | + +----------------------------------------------------+---------+ + | (a) Victoria alpine areas | 50 | + +----------------------------------------------------+---------+ + | (b) Victoria general (excluding alpine areas) | 100 | + +----------------------------------------------------+---------+ + | **Western Australia** | 80 | + +----------------------------------------------------+---------+ + +.. note:: The FDI values may be able to be refined within a + jurisdiction or region where sufficient climatological data + is available and in consultation with the relevant + regulatory authority. + +.. note:: The FDI values were provided by the Australasian Fire and + Emergency Service Authorities Council (AFAC). + +.. note:: Alpine and sub-alpine areas are defined as per the National + Construction Code, Volume 2 [NCCV2]_. + + +.. _classified_vegetation: + +Vegetation classification +------------------------- + +The vegetation of the site is classified in accordance with the +guidance provided in Table 2.3 and the corresponding figures in AS +3959--2009. Where there is more than one vegetation type, each +vegetation type is classified separately with the worst case scenario +applied. For example, if there is a mix of grassland and shrubland, +then the vegetation would be classified as shrubland, as this results +in a higher BAL. + +.. note:: The predominant vegetation type of a site may not + necessarily be the worst case scenario. + +In general, the land cover datasets often only present the predominant +vegetation type. Therefore, we cannot always determine the "worst +case" value of BAL. This would also be borne out by any ground +validation exercise. + +AS 3959--2009 provides a list of exclusions for low threat vegetation +and non-vegetated areas, where the BAL is classified as LOW. This +includes vegetation greater than 100 metres from the site, small (< 1 +ha) areas of vegetation that are also more than 100 metres from other +vegetation and low threat vegetation that includes grassland managed +in minimal fuel conditions. This includes lawns, golf courses, +orchards and cultivated gardens, amongst others. Non-vegetated areas +include waterways, roads, buildings, footpaths and rocky outcrops. + +Table 2.3 in AS 3959--2009 sets out seven major vegetation +classifications:: + +* Forest +* Woodland +* Shrubland +* Scrub +* Mallee/mulga +* Rainforest +* Grassland + +Each of these major vegetation classifications has between one and +eleven types, each of which has an indicative figure in the +Standard. See Figures 2.3 and 2.4(A) to 2.4(G) in the Standard for +these figures. There is also a brief text description of the +vegetation types (height, foliage cover, habit, etc.). + +.. note:: Overstoreys of open woodland, low open woodland, tall open + shrubland and low open shrubland should be classified to the + vegetation type on the basis of their understoreys; others + to be classified on the basis of their overstoreys. + +Distance to vegetation +---------------------- + +The distance to from the site to the classified vegetation is measured +in the *horizontal plane*. + +.. figure:: /docs/images/001_bal_vegetation_distance.png + :align: center + :width: 300 pt + + Determination of distance from site from classified vegetation. The + measurement is the horizontal distance, from Point A to + Point B. From AS 3959--2009. + +In the above figure, the distance from the classified vegetation to +the site is the same in all three cases, irrespective of the slope +over the intervening distance. In |project_name|, the effective +distance is measured betwen the centre of grid cells of the input +raster elevation data. + +Effective slope under the classified vegetation +----------------------------------------------- + +In determining BAL, 'slope' refers to the slope under the vegetation +in relation to the building. It is not the slope between the +vegetation and the site. The slope of the land under the classified +vegetation has a direct influence on the rate of fire spread, the +severity of the fire and the ultimate level of radiant heat flux. + +The definition of upslope and downslope is the definition of the +slope, relative to the site being evaluated. If the slope of the land +under the classified vegetation is **downhill** from the edge of the +classified vegetation nearest the site, then the slope is considered +**downslope**. If the slope of the land under the classified +vegetation is **uphill** from the edge of the classified vegetation +nearest the site, then the slope is considered **upslope**. + +.. figure:: /docs/images/001_bal_effective_slope.png + :align: center + :width: 300 pt + + Determination of effective upslope and downslope. From AS + 3959--2009. + +Determine BAL from appropriate table +------------------------------------ + +AS 3959-2009 provides a set of lookup tables, from which we can +determine the BL based on a combination of the FDI, distance from +classified vegetation and effective slope. + + + + +.. [NCCV2] National Construction Code, + Volume 2. http://www.abcb.gov.au/Resources/Publications/NCC/NCC-2016-Volume-Two +.. [1] Noble, I. R., G. A. V. Bary and A. M. Gill (1980): McArthur's + fire-danger meters expressed as equations. *Australian Journal + of Ecology*, **5**, pp 201--203, + DOI:10.1111/j.1442-9993.1980.tb01243.x diff --git a/docs/training/data.rst b/docs/training/data.rst new file mode 100644 index 0000000..484113a --- /dev/null +++ b/docs/training/data.rst @@ -0,0 +1,164 @@ +.. _data_requirements: + +Data requirements +================= + +|project_name| requires only two datasets to determine BAL -- a +classified vegetation dataset and a digital elevation model. With +these two datasets, it is possible to determine the slope and aspect +of a site, and the classified vegetation types described in AS +3959--2009, to enable determination of BAL. + +Digital elvation model +---------------------- + +A digital elevation model (DEM) is a digital model that represents a +geographic location's height above mean sea level. DEM's are developed +by a wide range of techniques, and widely varying horizontal grid +resolutions. + +At the national scale, Geoscience Australia has published the +1-arcsecond Shuttle Radar Topography Mission (SRTM) Digital Elevation +Models Version 1.0 (see +http://www.ga.gov.au/metadata-gateway/metadata/record/gcat_72759), +which is freely accessible. This DEM has a grid resolution of +approximately 30 m by 30 m (at the equator). There are also other +DEM's available through the `Geoscience Australia Data and +Publications Search portal +`_. Other organisations may +have higher-resolution and more up-to-date DEMs available for use in +the |project_name|. + +For the |project_name|, it is recommended to use a DEM with a +horizontal grid resolution comparable to the SRTM DEM, or higher for +best results. + +Format +...... + +Any `raster format supported by ESRI ArcGIS 10.2 +`_ +can be used in |project_name|. 32-bit floating point data in either +GeoTIFF or the native ESRI Grid format is recommended. + +.. _dem_projection: + +Projection +.......... + +The input DEM must be presented in a projected coordinate system, with +a linear unit of metres. Projected coordinate systems such as +Universal Transverse Mercator (UTM), or the Map Grid of Australia +(MGA) are suitable for projecting elevation data for use in the +|project_name|. + +.. warning:: The |project_name| will fail to execute if the input DEM + is in a geographic coordinate system. + +For the western portion of Western Australia, the `GDA94/MGA Zone 50 +`_ projection +would be an appropriate choice of projected coordinate system. + +Vegetation data +--------------- + +A classified vegetation dataset is required for determination of +BAL. The availability of classified vegetation datasets is varied, and +the clssifications used are similarly diverse, depending on the +application for which they were intended and the methods used to +derive them. + +For the examples used in this training workshop, we have used the +`National Vegetation Information System (NVIS) +`_, +which provides information on the extent and distribution of +vegetation types in Australian landscapes. This data has a horizontal +resolution of 100 m by 100 m. Other organisations may have +higher-resolution and more up-to-date classified vegetation datasets +available for use in the |project_name|. + +For optimal results, it is recommended to use a classified vegetation +dataset that is of a comparable resolution to the DEM used. + +.. attention:: The classified vegetation raster must be stored in the + same directory as the input DEM raster. The BAL + calculation script will fail if the rasters are not in + the same directory. + +Format +...... + +Any `raster format supported by ESRI ArcGIS 10.2 +`_ +can be used in |project_name|. Generally, an unsigned integer data +type will be sufficient to describe the classified vegetation +type. Either GeoTIFF or the native ESRI Grid format is recommended. + + +Classification +.............. + +The vegetation data needs to represent different classification +types. Ideally, the data will match the vegetation classes set out in +AS 3959--2009. These are numbered 1--7 and are defined as follows: + +.. table:: Classification of vegetation. After Table 2.3, AS 3959--2009. + ++-------+------------------+----------------------------------------------+ +| Value | Classification | Description | ++-------+------------------+----------------------------------------------+ +| 1 | Forest | Tall, open forest, tall woodland, open | +| | | | +| | | forest, low open forest, pine plantation | ++-------+------------------+----------------------------------------------+ +| 2 | Woodland | Woodland, open woodland, low woodland, low | +| | | | +| | | open woodland, open shrubland | ++-------+------------------+----------------------------------------------+ +| 3 | Shrubland | Closed heath, open heath, low shrubland | ++-------+------------------+----------------------------------------------+ +| 4 | Scrub | Closed scrub, open scrub | ++-------+------------------+----------------------------------------------+ +| 5 | Mallee/Mulga | Tall shrubland | ++-------+------------------+----------------------------------------------+ +| 6 | Rainforest | Tall closed forest, closed forest, low | +| | | | +| | | closed forest | ++-------+------------------+----------------------------------------------+ +| 7 | Grassland | Low open shrubland, hummock grassland, | +| | | | +| | | closed tussock grassland, tussock grassland, | +| | | | +| | | open tussock, sparse open tussock, dense | +| | | | +| | | sown pasture, sown pasture, open herbfield, | +| | | | +| | | sparse open herbfield | ++-------+------------------+----------------------------------------------+ + + +The input data must be in this numerical format for the |project_name| +to execute correctly. Values other than those listed here will be +ignored and may produce incorrect BAL values. + +The |project_name| provides users with the option to map their +classified vegetation to the required classes. By default, the mapping +matches the numerical values from NVIS to the required AS 3959--2009 +values. + +Projection +.......... + +The input classified vegetation dataset must be presented in a +projected coordinate system, with a linear unit of metres. Projected +coordinate systems such as Universal Transverse Mercator (UTM), or the +Map Grid of Australia (MGA) are suitable for projecting elevation data +for use in the |project_name|. + +.. warning:: The |project_name| will fail to execute if the input + vegetation classification data is in a geographic + coordinate system. + +For the western portion of Western Australia, the `GDA94/MGA Zone 50 +`_ projection +would be an appropriate choice of projected coordinate system. diff --git a/docs/training/execution.rst b/docs/training/execution.rst new file mode 100644 index 0000000..8856988 --- /dev/null +++ b/docs/training/execution.rst @@ -0,0 +1,250 @@ +.. _running_bal_training: + +Runnning the tool +================= + +To calculate the BAL, we use the **BAL calculation** tool within the **BAL** +toolbox installed in ArcGIS 10.2. + +Select the :menuselection:`BAL --> BAL calculation` tool, see :numref:`select_bal_training`. + +.. _select_bal_training: + +.. figure:: /docs/images/select_bal.jpg + :align: center + :alt: Select the tool **BAL calculation**. + :figclass: align-center + + Select the tool **BAL calculation**. + +Then the **BAL calculation** window is open, see :numref:`bal_window_training`. + +.. _bal_window_training: + +.. figure:: /docs/images/BAL_calculation_window.jpg + :align: center + :alt: The **BAL calculation** window. + :figclass: align-center + + The **BAL calculation** window. + + +Getting help from within the toolbox +------------------------------------ + +On the left of the dialog window is the input fields, options and the +output fields. We will work through these in turn. On the right, help +content for each of the dialog's entry fields are displayed. As you +move to different entry fields the content in this panel will update. + +You can toggle the tool help on and off, by clicking the +:guilabel:`Tool Help` button on the lower right corner of the dialog +window. + +Another way to access the help is via the menus. Right click on the +:menuselection:`BAL calculation` script and select "Help". This will +display the full help menu for the |project_name|. + +.. _bal_toolbox_help: + +.. figure:: /docs/images/001_bal_toolbox_help.png + :align: center + :alt: Accessing the BAL Toolbox help menu. + :figclass: align-center + + Accessing the BAL Toolbox help menu. + +Input fields +------------ + +Input digital elevation model +............................. + +The first input field is the digital elevation model. Click the folder +icon button |folder_icon| to browse to the location of the required +DEM raster file. The DEM **must** be in a projected coordinate system, +with a linear unit of metres. Additional information can be found in +the :ref:`dem_projection` section. + +.. figure:: /docs/images/001_bal_input_dem.png + :align: center + :alt: DEM input field + :figclass: align-center + + Digital Elevation Model input field. + +.. _vegetation_input: + +Input classified vegetation raster +.................................. + +The second input field is for the classified vegetation layer. Again, +click the folder icon button |folder_icon| to browse to the location +of the required classified vegetation raster file. As with the DEM, +the classified vegetation raster should be in a projected coordinate +system, matching the DEM, though this is not essential. + +.. figure:: /docs/images/001_bal_input_vegetation.png + :align: center + :alt: Classified vegetation input field + :figclass: align-center + + Classified vegetation raster input field. + +The next input field is the vegetation reclassification table. It is +presumed that the input classified vegetation dataset will not exactly +match the classification required in AS 3959-2009 (see +:ref:`classified_vegetation`). For this reason, the |project_name| +allows users to reclassify the input dataset to the values required +for calculation of the BAL. + +.. figure:: /docs/images/001_bal_input_vegetation_classification.png + :align: center + :alt: Vegetation reclassification table + :figclass: align-center + + Vegetation reclassification table, pre-populated with values to + reclassify National Vegetation Information System data to AS + 3959--2009 values. + +The reclassification table is pre-populated with values matching the +National Vegetation Information System (NVIS) data. Under the "Old +values" column, the integer values representing different vegetation +classes in the NVIS classes. Under the "New Values" column are the +integer values to which the NVIS classes will be mapped. These new +values represent the seven classes set out in AS 3959--2009. + +A different clasified vegetation dataset will necessitate a change to +the reclassification table. You can add and delete entries using the +:guilabel:`Add Entry` and :guilabel:`Delete Entries` buttons. You can +save the existing table using he :guilabel:`Save...` button, or load a +pre-existing table using the :guilabel:`Load...` button. + +Classifying another vegetation dataset should be done in consultation +with someone with expertise in vegetation classification. While AS +3959--2009 does provide some descriptive information on the vegetation +types in each of the primary 7 classes and the sub-classes (Table +2.3). + +Output path +........... + +The output path is specified in the next field. Click the folder +button |folder_icon| to browse to a folder that you want to store the +results of the BAL analysis. + +.. figure:: /docs/images/001_bal_output_path.png + :align: center + :alt: BAL toolbox output path + :figclass: align-center + + Output path field entry. + +.. note:: There are some limitations to the name length and file path + length in ESRI applications. The maximum number of + characters in the full path name (including file name) is + 128 characters. In testing, each folder name's length should + be restricted to a maximum of 8 characters. + + +FDI value +......... + +The Fire Danger Index (FDI) value used to evaluate BAL is defined in +AS 3959--2009, and is based on the jurisdiction (i.e. State or +Territory), or a sub-region within jurisdictions, as defined in the +National Construction Code, Volume 2 [NCCV2]_. The default value is an +FDI of 80, but values of 100, 80, 50 and 40 can be selected. The +:guilabel:`Help` sidebar provides the FDI values for different +regions, as per AS 3959--2009. + +.. figure:: /docs/images/001_bal_fdi_value.png + :align: center + :alt: BAL toolbox FDI value options + :figclass: align-center + + Fire Danger Index (FDI) options menu. + + +Extent +...... + +The :guilabel:`Extent` option provides a way to select the area for +analysis. There are four options in the dropdown menu: :guilabel:`Default`, +:guilabel:`Union of Inputs`, :guilabel:`Intersection of Inputs` and :guilabel:`As Specified Below`. + +.. figure:: /docs/images/001_bal_extent_options.png + :align: center + :alt: Extents options + :figclass: align-center + + Extents options menu. + +The :guilabel:`Default` option is the common area between the DEM and +the classified vegetation data layers. It is not possible to calculate +BAL in areas where there is only one input data (i.e. DEM or +classified vegetation). The :guilabel:`As Specified Below` option +allows users to manually select an area of interest. This may be a +subset of the complete coverage of teh DEM and classified +vegetation. If the specified region is larger than the intersection of +the inputs, then the extent of the intersection of the inputs will be +used. + +.. note:: If specifying the extents manually, these should be in + projected coordinates, i.e. in the coordinate system the DEM + uses. + + +Run the toolbox +--------------- + +Once the input datasets have been specified and the other options set, +you can now click the :guilabel:`OK` button to execute the +analysis. When the analysis runs, a dialog window will appear and +start displaying a series of messages. + +.. figure:: /docs/images/001_bal_calculation_progress.png + :align: center + :alt: BAL calculation progress dialog + :figclass: align-center + + Progress dialog for the BAL calculation. + +Depending on the extent of the region, and the horizontal resolution +of the DEM and classified vegetation data, the analysis will take +anywhere from less than a minute to several hours to execute. When the +analysis is complete, the BAL calculation dialog will indicate +successful completion: + +.. figure:: /docs/images/001_bal_calculation_log.png + :align: center + :alt: BAL calculation completed + :figclass: align-center + + Completed dialog for the BAL calculation. Note the final line says + "Succeeded at...". + +Click the :guilabel:`Close` button in the top right corner to close +the BAL calculation dialog. You can review the log messages by opening +the :guilabel:`Results` panel in ArcCatalog: +:menuselection:`Geoprocessing --> Results --> Current Session --> BAL +calculation --> Messages`. + +Check the output +................ + +On successful execution of the BAL calculation tool, there should be 9 +raster datasets in the output folder. There are eight, for each of the +cardinal directions (north, northeast, east, etc.). A ninth raster +dataset represents the maximum BAL of all eight directions for each +grid cell. + +The output rasters are ERDAS Imagine raster files (with a :samp:`.img` +extension), 32-bit floating point data, using the same projected +coordinate system as the input DEM. + +The data can now be added to an ArcMap session for inspection. + + +.. [NCCV2] National Construction Code, + Volume 2. http://www.abcb.gov.au/Resources/Publications/NCC/NCC-2016-Volume-Two diff --git a/docs/training/index.rst b/docs/training/index.rst new file mode 100644 index 0000000..f0494d8 --- /dev/null +++ b/docs/training/index.rst @@ -0,0 +1,25 @@ +.. _training_session: + +Bushfire Attack Level Toolbox Training Workshop +=============================================== + +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + objectives + agenda + intro + bal + data + install + setup + execution + extraction + faqs + + + + diff --git a/docs/training/install.rst b/docs/training/install.rst new file mode 100644 index 0000000..7116af6 --- /dev/null +++ b/docs/training/install.rst @@ -0,0 +1,106 @@ +.. _install_training: + +Installing the |project_name| +============================= + +Instructions for installing the |project_name| are given in the +:ref:`User Guide ` and :ref:`Set up ` sections. + + + +Testing the installation +------------------------ + +.. important:: Testing the installation before using it will allow you + to identify any issues with the installation of the + |project_name| before using it. Without testing the + toolbox first, you may obtain results that are + inconsistent with the intented application of the + toolbox. + +The code includes a suite of unit tests that ensure elements of the +code base work as expected. The code should be tested before running +the toolbox. Users will need to install the `Nose +`_ package to run +these tests. + +The test suite can be run from the main directory. On Windows, run the +:command:`run_test_all.cmd` script from the main BAL directory. + +.. figure:: /docs/images/001_bal_unittest_execution.png + :align: center + :width: 300 pt + + Running the BAL test suite in a Windows command prompt. + +.. figure:: /docs/images/001_bal_unittest_complete.png + :align: center + :width: 300 pt + + Windows command prompt showing successful completion of the test + suite. Notice the last few messages indicating the number of tests + and "OK". + +If the test suite fails, then there will be a message indicating which +test failed and a description of the failure. If you get this, copy +the description and create a ticket on the |project_name| `Issue +Tracker `_. + + +Adding the toolbox into ArcGIS 10.2 +----------------------------------- + +Follow the steps below to add the |project_name| into ArcGIS 10.2: + +* Open the ArcToolbox window. See :numref:`arctoolbox1`. + +.. _arctoolbox1: + +.. figure:: /docs/images/arctoolbox.jpg + :align: center + :alt: ArcToolbox window. + :figclass: align-center + + The ArcToolbox window. + +* Right click **ArcToolbox** at the top of the window, see + :numref:`rightclickarctoolbox1`. + +.. _rightclickarctoolbox1: + +.. figure:: /docs/images/rightclick_arctoolbox.jpg + :align: center + :alt: Right click ArcToolbox in the ArcToolbox window. + :figclass: align-center + + Right click **ArcToolbox** in the ArcToolbox window. + +* Select **Add Toolbox...**, a dialog box is open. See + :numref:`addtoolboxdialog1`. + +.. _addtoolboxdialog1: + +.. figure:: /docs/images/addtoolbox_dialog.jpg + :align: center + :alt: Add toolbox dialog window. + :figclass: align-center + + The **Add Toolbox** dialog window. + +* In the dialog box, navigate to the location of the package, for + example :file:`C:\\bal`, you will find the **BAL.tbx**. See :numref:`addtoolboxdialog1`. + + +* Select **BAL.tbx** and click **Open**, a new toolbox called **BAL** + is added to the ArcToolbox. See :numref:`baltoolboxloaded1`. + +.. _baltoolboxloaded1: + +.. figure:: /docs/images/BAL_toolbox.jpg + :align: center + :alt: BAL toolbox is added. + :figclass: align-center + + The **BAL** toolbox is added. + + diff --git a/docs/training/intro.rst b/docs/training/intro.rst new file mode 100644 index 0000000..c412f5a --- /dev/null +++ b/docs/training/intro.rst @@ -0,0 +1,98 @@ +.. _training_intro: + +Introduction +============ + +About Geoscience Australia +-------------------------- + +Geoscience Australia is the geoscience advisor to the Australian +Government on matters of national importance, and custodian of the +geographical and geological data and knowledge of the nation. + +By understanding the geological history and geospatial aspects of our +continent, we build our knowledge and capability to prepare us for the +future. + +We deliver a wide range of products that address important and +significant national issues to assist government and the community to +make informed decisions about the use of natural resources, the +management of the environment, and community safety. + +Through six key strategic priority areas, Geoscience Australia +provides applied research and information for the Australian community +to obtain sustainable economic, social and environmental benefits. + +* Building Australia's Resource Wealth +* Ensuring Australia's Community Safety +* Securing Australia's Water Resources +* Managing Australia's Marine Jurisdictions +* Providing Fundamental Geographic Information +* Maintaining Geoscience Knowledge and Capability + +We apply our geoscience knowledge and capability to acquire, store and +manage Australia's national fundamental geological and geographic +information. + +This enables Australia to make critical decisions regarding our +natural resource potential and marine environment, and helps to build +our resilience to natural hazards. + +It also ensures sustainable Australian communities by managing our +precious water resources. + +Geoscience Australia continues to actively promote Australia's mineral +and energy resources to international trade partners, increasing +awareness of the opportunities Australia's vast resource sector +provides. + +Working with our government partner organisations, we have broadened +our scope of work in support of Australia's efforts to reduce the +impact of natural disasters in our region. + +Community Safety Branch +....................... + + +.. image:: /docs/images/001_ga_community_safety.png + :align: center + :width: 300 pt + :alt: Community Safety strategic plan + +In Australia we are exposed to many hazards - fires, floods, +earthquakes, tsunamis, and extreme weather. These natural events +transform into natural disasters when lives are lost, and property is +destroyed. Geoscience Australia understands these hazards and the +risks they pose to communities. + +As our population grows, people and infrastructure become exposed to +hazards. It is not enough to simply respond, we must prepare. + +To protect the vulnerable we must understand the risks they face and +managing the impact of natural hazards to avoid disaster. + +**How do we ensure Australia's community safety?** + +We must recognise the worst case, to plan for the best outcome and +consider how we develop our unique landscape. Combining short-term +response and long term planning, making decisions based on evidence +specific to Australia's circumstances. + +In times of confidence and crisis, Geoscience Australia models and +measures the hazards that put us in danger. + +We identify what parts of Australia are most at risk, and assesses the +potential financial and social costs facing our environment, our +industries and the people they support. + +We must understand how hazards impact our society, to allow +communities to prepare for emergencies, to provide advice to prevent +emerging disasters and to build a safer and more resilient future, for +us all. + +The vision for the Community Safety Branch is to develop and deliver +authoritative nationally consistent data and information to enable +decision makers, governments, businesses and the community to better +understand the consequences of hazard events and to contribute to more +resilient communities. + diff --git a/docs/training/objectives.rst b/docs/training/objectives.rst new file mode 100644 index 0000000..3ac058f --- /dev/null +++ b/docs/training/objectives.rst @@ -0,0 +1,29 @@ +.. _objectives: + +Objectives +========== + +This training workshop provides an introduction to the |project_name| toolbox, what the |project_name| toolbox does (and does not do) and how it can be used to support emergency management activities. By the end of the workshop, participants should be able to demonstrate the following skills and knowledge: + +* Understand the purpose of the Bushfire Attack Level +* Understand the limitations of the |project_name| toolbox +* Be able to install and test the |project_name| toolbox +* Run example calculations of the |project_name| + +Target audience +--------------- + +* Officers supporting bushfire planning and management activities +* Officers responsible for managing vulnerable infrastructure assets + +Prerequisites +------------- + +* An understanding of Geographic Information Systems; +* An understanding of bushfire hazards and the impacts on assets; +* A computer with: + + * Windows (XP, 7, 8, 10) + * ArcGIS 10.2 or later, including the Python extensions + * Internet access (to download the toolbox) + diff --git a/docs/userguide/background.rst b/docs/userguide/background.rst new file mode 100644 index 0000000..05c522a --- /dev/null +++ b/docs/userguide/background.rst @@ -0,0 +1,197 @@ +Background +============ + +The algorithm used to calculate the BAL is based on Method 1 in the +`Australian Standard AS 3959 (2009)--*Construction of buildings in +bushfire-prone areas* +`_. +Method 1 is a simplified procedure that involves five steps to +determine BAL, and is subject to limitations on the circumstances in +which it can be used. + +.. warning:: This method is not valid where the effective slope under the + classified vegetation is more than 20 degrees downslope. Within + the BAL toolbox, where the slope is greater than 20 degrees a + constant value of 200 is used for the BAL. + +Procedure to determine BAL +-------------------------- + +According to the Standard AS 3959 (2009), the calculation of BAL involves +five steps. + + +Step 1 +++++++ + +Select the relevant Fire Danger Index (FDI) based on the locations +according to `Table 2.1 +`_ +in the Australian Standard AS 3959 (2009). For example, from Table +2.1, the FDI for Western Australia is 80. + +.. table:: Jurisdictional and regional values for FDI (adapted from + Table 2.1, `AS 3959, 2009 + `_). + :widths: 50, 10 + + +----------------------------------------------------+---------+ + | **State/region** | FDI | + +----------------------------------------------------+---------+ + | **Australian Capital Territory** | 100 | + +----------------------------------------------------+---------+ + | **New South Wales** | - | + +----------------------------------------------------+---------+ + | (a) Greater Hunter, Greater Sydney, | | + | Illawarra/Shoalhaven, Far South Coast, | 100 | + | | | + | and Southern Ranges fire weather districts | | + +----------------------------------------------------+---------+ + | (b) NSW alpine areas | 50 | + +----------------------------------------------------+---------+ + | (c) NSW general (excluding alpine areas, Greater | | + | Hunter, Greater Sydney, | | + | | 80 | + | Illawarra/Shoalhaven,Far South Coast and | | + | Southern Ranges fire weather districts) | | + +----------------------------------------------------+---------+ + | **Northern Territory** | 40 | + +----------------------------------------------------+---------+ + | **Queensland** | 40 | + +----------------------------------------------------+---------+ + | **South Australia** | 80 | + +----------------------------------------------------+---------+ + | **Tasmania** | 50 | + +----------------------------------------------------+---------+ + | **Victoria** | - | + +----------------------------------------------------+---------+ + | (a) Victoria alpine areas | 50 | + +----------------------------------------------------+---------+ + | (b) Victoria general (excluding alpine areas) | 100 | + +----------------------------------------------------+---------+ + | **Western Australia** | 80 | + +----------------------------------------------------+---------+ + +.. note:: The FDI values may be able to be refined within a + jurisdiction or region where sufficient climatological data + is available and in consultation with the relevant + regulatory authority. + +.. note:: The FDI values were provided by the Australasian Fire and + Emergency Service Authorities Council (AFAC). + +.. note:: Alpine and sub-alpine areas are defined as per the National + Construction Code, Volume 2 [NCCV2]_. + +Step 2 +++++++ + +Classify the input vegetation dataset into seven vegetation types +defined in Table 2.3 in the Standard AS 3959 (2009). See `AS 3959 +`_ +for indicative illustrations and detailed descriptions of the range of +vegetation types. + +* 1: Forest, +* 2: Woodland, +* 3: Shrubland, +* 4: Scrub, +* 5: Mallee/Mulga, +* 6: Rainforest, +* 7: Grassland/Tussock moorland. + +Where there is more than one vegetation type, the classification +should be based on the vegetation type that results in the worst case +scenario. + +.. note:: Classificatied vegetation datasets are likely to be classified + according to the predominant vegetation in a grid cell, + which is not necessarily the worst case scenario. + +The numbers from 1 to 7 are assigned to these vegetation classes +respectively for calculating BAL. + +Step 3 +++++++ + +Calculate the distance of the site from the classified vegetation. +According to AS 3959 (2009), the vegetation is only considered +when its distance from the site of interest is **less than 100 metres**. +Within the BAL toolbox, this is done spatially for each grid point +located within 100 metres of vegetation. + +Step 4 +++++++ + +Determine the effective slope (the gradient from each cell) and aspect +under the classified vegetation. Here, 'slope' refers to the slope +under the classified vegetation in relation to the building - not the slope +between the vegetation and the building. Where the slope of the land under +the vegetation is downhill from the edge nearest the building, this slope is +regarded as a downslope that will be further analysed. Otherwise the +slope is regarded as an upslope. + +.. figure:: /docs/images/Slope_determination.JPG + :align: center + :alt: Determination of slope. + :figclass: align-center + + Determination of effective slope. Figure 2.2 from AS 3959 (2009). + +When calculating BAL, upslopes and flat land is treated as a single +category. For downslopes, the Standard breaks them down into five +classes: + +* 0 < downslope <= 5 degrees +* 5 < downslope <= 10 degrees +* 10 < downslope <= 15 degrees +* 15 < downslope <= 20 degrees +* > 20 degrees (beyond consideration of Method 1) + +Step 5 +++++++ + +Determine the BAL from an appropriate table defined in AS 3959 (2009) +based on the input FDI. For example, for Western Australia, the FDI is +80 and thus Table 2.4.3 is adopted for deriving the BAL. + +Within the BAL toolbox, these tables are included within the Python code, +and are automatically referenced based on the user's inputs. + +Deriving and interpreting BAL +----------------------------- + +We consider eight cardinal directions: north, northeast, east, +southeast, south, southwest, west, and northwest. For each cardinal +direction, we consider the neighbouring cells up to 100 metres from +the site. We calculate the BAL for each neighbouring cell with regards +to the site based on the neighbouring cell's: + +* vegetation type +* upslope or downslope orientation and grade (slope) +* its distance to the site + +The calculated BAL falls into one of the following categories: +12.5, 19, 29, 40, 100, where 100 represents Fire Zone (FZ). + +.. note:: Where the downslope is greater than 20 degrees and there is + vegetation, a constant value of 200 is given to the BAL. + +The maximum BAL is selected among all neighbouring cells in a given +cardinal direction to represent the BAL for that direction. + +The final BAL for the site of interest is determined by selecting the +maximum BAL from all eight cardinal directions. + +The final BAL values correspond to a predicted level of exposure during +a bushfire, and are associated with an accompanying construction code. + +.. figure:: /docs/images/BAL_table.JPG + :align: center + :alt: BAL interpretation. + :figclass: align-center + + BAL and corresponding exposure and construction codes. Table 3.1 from AS 3959 (2009). + +.. [NCCV2] National Construction Code, Volume 2. http://www.abcb.gov.au/Resources/Publications/NCC/NCC-2016-Volume-Two + diff --git a/docs/bal.rst b/docs/userguide/bal.rst similarity index 100% rename from docs/bal.rst rename to docs/userguide/bal.rst diff --git a/docs/calculate_bal.rst b/docs/userguide/calculate_bal.rst similarity index 100% rename from docs/calculate_bal.rst rename to docs/userguide/calculate_bal.rst diff --git a/docs/userguide/contributing.rst b/docs/userguide/contributing.rst new file mode 100644 index 0000000..3261bf9 --- /dev/null +++ b/docs/userguide/contributing.rst @@ -0,0 +1,62 @@ +.. _contributing: + +Contributing code +================= + +The preferred way to contribute to |project_name| is to fork the +`main repository `_ on GitHub: + +1. Fork the `project repository `_: + click on the 'Fork' button near the top of the page. This creates + a copy of the code under your account on the GitHub server. + +2. Clone this copy to your local disk:: + + $ git clone git@github.com:YourLogin/bal.git + $ cd tcrm + +3. Create a branch to hold your changes:: + + $ git checkout -b my-feature + + and start making changes. Never work in the ``master`` branch! + +4. Work on this copy on your computer using Git to manage version + control. When you're done editing, do:: + + $ git add modified_files + $ git commit + + to record your changes in Git, then push them to GitHub with:: + + $ git push -u origin my-feature + +Finally, go to the web page of the your fork of the BAL repo, +and click 'Pull request' to send your changes to the maintainers for +review. This will send an email to the code managers. + +(If any of the above seems like magic to you, then look up the +`Git documentation `_ on the web.) + +It is recommended to check that your contribution complies with the +following rules before submitting a pull request: + +- All public methods should have informative docstrings with sample + usage presented as doctests when appropriate. + +- When adding additional functionality, provide at least one + example script in the ``examples/`` folder. Have a look at other + examples for reference. Examples should demonstrate why the new + functionality is useful in practice. + +- At least one paragraph of narrative documentation with links to + references in the literature (with PDF links when possible) and + an example. + +You can also check for common programming errors with the following +tools: + +- Check your code complies with good unittest coverage:: + + $ pip install nose coverage + $ nosetests --with-coverage path/to/tests_for_package diff --git a/docs/examples.rst b/docs/userguide/examples.rst similarity index 52% rename from docs/examples.rst rename to docs/userguide/examples.rst index f5a9c3d..86d671c 100644 --- a/docs/examples.rst +++ b/docs/userguide/examples.rst @@ -4,11 +4,14 @@ An Example Input ----- + **Input DEM:** -jerram_dem: Esri Grid format, MGA 50, 25 m resolution. See Figure 4.8. The input DEM is located under the **examples\\input** folder. +jerram_dem: Esri Grid format, MGA 50, 25 m resolution. See :numref:`dem_input` +The input DEM is located under the **examples\\input** folder. -.. figure:: dem_example.jpg +.. _dem_input: +.. figure:: /docs/images/dem_example.jpg :align: center :alt: Example DEM data at Jerramungup, WA. :figclass: align-center @@ -17,9 +20,12 @@ jerram_dem: Esri Grid format, MGA 50, 25 m resolution. See Figure 4.8. The input **Input vegetation:** -jerram_veg: Esri Grid format, GDA 1994 Australia Albers, 100 m resolution. See Figure 4.9. The input vegetation dataset is located under the **examples\\input** folder. +jerram_veg: Esri Grid format, GDA 1994 Australia Albers, 100 m resolution. +See :numref:`veg_input`. The input vegetation dataset is located under the +**examples\\input** folder. -.. figure:: veg_example.jpg +.. _veg_input: +.. figure:: /docs/images/veg_example.jpg :align: center :alt: Example vegetation data at Jerramungup, WA. :figclass: align-center @@ -29,7 +35,12 @@ jerram_veg: Esri Grid format, GDA 1994 Australia Albers, 100 m resolution. See F **Input vegetation reclassification map:** -There are many classes in the original vegetation. To derive the target vegetation classes described in the Standard (1: Forest, 2: Woodland, 3: Shrubland, 4: Scrub, 5: Mallee/Mulga, 6: Rainforest, 7: Grassland/Tussock moorland.), the remap string is defined as: "1 6;2 1;3 1;4 1;5 13 2;14 5;15 18 3;19 22 7;23 4;24 25 NODATA;26 4;27 28 NODATA;29 4;30 1;31 2;32 5;99 NODATA". +There are many classes in the original vegetation. To derive the +target vegetation classes described in the Standard (1: Forest, 2: +Woodland, 3: Shrubland, 4: Scrub, 5: Mallee/Mulga, 6: Rainforest, +7: Grassland/Tussock moorland.), the remap string is defined as: +"1 6;2 1;3 1;4 1;5 13 2;14 5;15 18 3;19 22 7;23 4;24 25 NODATA;26 +4;27 28 NODATA;29 4;30 1;31 2;32 5;99 NODATA". **Output path:** @@ -44,21 +55,27 @@ Default value 80 is selected. Default is selected. -After all input parameters are defined, the fields in the BAL calculation window are all populated. See Figure 4.10. +After all input parameters are defined, the fields in the BAL calculation +window are all populated. See :numref:`example_bal_calc`. -.. figure:: example_BAL_calculation.jpg +.. _example_bal_calc: +.. figure:: /docs/images/example_BAL_calculation.jpg :align: center :alt: Example input parameters within BAL calculation window. :figclass: align-center - Example input parameters within BAL calculation window. + Figure 6.3 Example input parameters within BAL calculation window. Process ------- -After clicking the **OK** button in the above window, the calculation starts running with a progress reporting in a pop-up window. When it finishes successfully, the pop-up window looks like Figure 4.11. +After clicking the **OK** button in the above window, the calculation starts +running with a progress reporting in a pop-up window. When it finishes +successfully, the pop-up window looks like :numref:`example_process`. + -.. figure:: example_process.jpg +.. _example_process: +.. figure:: /docs/images/example_process.jpg :align: center :alt: Example pop-up window when the calculation finishes. :figclass: align-center @@ -68,13 +85,15 @@ After clicking the **OK** button in the above window, the calculation starts run Output ------ -Nine rasters are produced under C:\\github\\bal\\examples\\output. Figure 4.12 displays the maximum BAL raster file named as bal_max.img for this example. +Nine rasters are produced under C:\\github\\bal\\examples\\output. +:numref:`bal_max` displays the maximum BAL raster file named as bal_max.img for this example. -.. figure:: bal_max.jpg +.. _bal_max: +.. figure:: /docs/images/bal_max.jpg :align: center :alt: Example output BAL at Jerramungup, WA. :figclass: align-center Example output BAL at Jerramungup, WA. - \ No newline at end of file + diff --git a/docs/userguide/execution.rst b/docs/userguide/execution.rst new file mode 100644 index 0000000..07ad7d3 --- /dev/null +++ b/docs/userguide/execution.rst @@ -0,0 +1,136 @@ +.. |beta| unicode:: U+003B2 .. GREEK SMALL LETTER BETA + +.. _execution: + +================ +Running the tool +================ + +To calculate the BAL, we use the **BAL calculation** tool within the +**BAL** toolbox installed in ArcGIS 10.2. + +Select the **BAL calculation** tool within the **BAL** toolbox, see +:numref:`select_bal`. + +.. _select_bal: + +.. figure:: /docs/images/select_bal.jpg + :align: center + :alt: Select the tool **BAL calculation**. + :figclass: align-center + + Select the tool **BAL calculation**. + +Then the **BAL calculation** window is open, see :numref:`bal_window`. + +.. _bal_window: + +.. figure:: /docs/images/BAL_calculation_window.jpg + :align: center + :alt: The **BAL calculation** window. + :figclass: align-center + + The **BAL calculation** window.Figure 5.1. + +Parameters within the tool +========================== + +**Input DEM raster:** + + Open your input DEM file from a specific location. The DEM + **must** be in a projected coordinate system with linear unit + metre. For example GDA94 / MGA zone 50 is a projected spatial + reference system and is suitable for use in the western part + of Western Australia. More information about GDA94 / MGA zone + 50 can be found `here + `_. + +**Input vegetation raster:** + + Open your input vegetation dataset from a specific location. + The vegetation dataset can be in either a geographical or a + projected coordinate system. It will be reprojected to the + same projection and same resolution as DEM by the BAL tool. + +**Vegetation reclassification:** + + Reclassify the input vegetation classes into those defined in + the Australian Standard AS 3959 (2009). There are seven + classes defined in the Standard. In this tool, we give each + class a unique number, i.e.: + + * 1: Forest, + * 2: Woodland, + * 3: Shrubland, + * 4: Scrub, + * 5: Mallee/Mulga, + * 6: Rainforest, + * 7: Grassland/Tussock moorland. + + The reclassification process needs to be considered by the user, + and will vary according to the input vegetation dataset. + + A sample reclassification map is entered for the example data. + The reclassification map needs to be changed by the users according + to their own input vegetation data. + +**Output path:** + + Define the output location. Note that this is asking for a folder to + write the output to, not a file name. + +**FDI value:** + + The input Fire Danger Index (FDI) value has four choices (100, + 80, 50, 40) based on the locations, which are specified in + AS 3959--2009. + + * **100**: Australian Capital Territory (ACT), part of New South + Wales (NSW) (Greater Hunter, Greater Sydney, + Illawarra/Shoalhaven, Far South Coast and Southern Ranges + fire weather districts), and Victoria general (excluding + alpine areas). + * **80**: NSW general (excluding alpine areas, and the areas with + FDI 100), South Australia (SA), and Western Australia (WA). + * **50**: NSW alpine areas, Tasmania, and Victoria alpine areas. + * **40**: Northern Territory (NT), and Queensland (Qld). + + Select the FDI value from a suite of values (100, 80, 50, + 40). The default value of 80 is applicable in Western + Australia. + +**Extent:** + + The extent is used to select the area of interest for which the + BAL will be calculated. The default output data extent will be where + you have consistent coverage of DEM and vegetation data within + the area of interest. + +.. note:: There is a limitation in raster file name length and file path + length in ArcGIS. For a raster name in ESRI Grid format, the maximum + number of characters is 13 and for full path name, the maximum + number of character is 128. For more information, `click here + `_. In + addition, as tested, each folder name's length should be restricted + to at most eight characters. + + + +Output +====== + +A suite of rasters are produced and stored in the output folder. They +represent the BAL for the area computed in each of eight cardinal +directions (E, S, W, N, NE, NW, SE and SW) and the maximum BAL of all +directions. :numref:`bal_output` is an example output. + +.. _bal_output: + +.. figure:: /docs/images/BAL_output.jpg + :align: center + :alt: An example BAL output window. + :figclass: align-center + + An example BAL output window. + + diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst new file mode 100644 index 0000000..5fe5334 --- /dev/null +++ b/docs/userguide/index.rst @@ -0,0 +1,46 @@ +.. Bushfire Attack Level Toolbox documentation master file, created by + sphinx-quickstart on Wed Apr 12 11:02:21 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Bushfire Attack Level Toolbox User Guide +======================================== + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + intro + background + install + setup + execution + examples + contributing + writing_documentation + + +The following documentation is extracted from the source code in-line +documentation and included in this document for the completeness of the +software package. It does not directly instruct users how to use the toolbox +to calculate the BAL. Instead, it might be useful for software engineers +or developers to review the source code and maintain or upgrade it in +the future. + +.. toctree:: + :maxdepth: 1 + :caption: Code documentation + + bal + calculate_bal + utilities + + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/userguide/install.rst b/docs/userguide/install.rst new file mode 100644 index 0000000..36a5c46 --- /dev/null +++ b/docs/userguide/install.rst @@ -0,0 +1,69 @@ +.. _installation: + +Installation +============ + +Installing BAL Toolbox is intended to be a simple process, requiring +only basic understanding of ArcGIS toolbox operations. It has been +installed and tested on ArcGIS 10.2. + + +Unzipping the toolbox +--------------------- + +The software package is delivered as a compressed zip file. Unzip the +toolbox into a location on your computer, for example :file:`C:\\bal`. Then +you will have stored all the files at folder :file:`C:\\bal`. + + +Dependencies +------------ + +* `Python `_ - v2.7 +* `Numpy `_ - v1.6.2 +* `Arcpy in ArcGIS 10.2 `_ + +.. warning:: ArcGIS 10.2 is packaged with a modified version of + ``Numpy``. In our experience, attempting to update the + ``Numpy`` package will cause the ``arcpy`` package to fail + catastrophically, and usually without reporting any error + message. We strongly recommend against trying to upgrade + the version of ``Numpy`` linked to your ``ArcGIS`` + installation. + +Setting the environment +------------------------ + +To enable BAL toolbox to run flawlessly, you may need to change some +environment settings. The important variable to set is the +``PYTHONPATH`` variable. This should be set to the path where you have +extracted the contents of the zip file. A complete discussion on +environment variables in Python is given in the `Python documentation +`_. + +Windows +~~~~~~~~ + +The Python documentation contains some simple instructions for setting +environment variables on Windows systems `here +`_. See `this link +`_ for setting the +variables on different Windows systems. + +Testing the installation +------------------------ + +The code includes a suite of unit tests that ensure elements of the +code base work as expected. The code should be tested before running +the toolbox. Users will need to install the `Nose +`_ package to run +these tests. + +The test suite can be run from the main directory. On Windows, run the +:command:`run_test_all.cmd` script from the main BAL directory. + + +If the test suite fails, there will be a message indicating which +test failed and a description of the failure. If you receive this, copy +the description and create a ticket on the |project_name| `Issue +Tracker `_. diff --git a/docs/userguide/intro.rst b/docs/userguide/intro.rst new file mode 100644 index 0000000..db57f5c --- /dev/null +++ b/docs/userguide/intro.rst @@ -0,0 +1,88 @@ +Introduction +============ + +Fire is a natural feature of the Australian landscape and remains an +ever-present threat. Bushfire threat analysis aims to inform the fire +authorities and the community of the bushfire hazard in an effort to +manage the risk posed to life, property and the environment. + +Bushfire Attack Level (BAL) is a measure of the severity of a +building's potential exposure to bushfire. It is defined in the +`Australian Standard AS 3959 (2009)--*Construction of buildings in +bushfire-prone areas* +`_, +to serve as a basis for establishing the requirements for construction, +to improve the protection of buildings from bushfire attack. The Standard +describes how to compute the bushfire attack level for any location +and directly links this to recommendations on the design of existing +or planned buildings. + +The BAL toolbox implements the rules described by Method 1 in AS +3959 (2009) by integrating them into a computational code that can be +run in the ESRI ArcGIS 10.2 environment. + + +Package structures +------------------ + +The toolbox name is **BAL.tbx**. This toolbox is associated with a +python script, **bal.py**, to derive BAL. The script **bal.py** links +to a python script **calculate_bal.py** and a module **Utilities**, +which includes supporting dictionaries defined in two python scripts: + +* value_lookup.py; +* bal_database.py. + +There are three more folders: + +* **docs**: holding the documentation files. + +* **tests**: holding the unit tests, scenario tests and their test data. + +* **examples**: holding the example input and output data. + + +Use limitations +--------------- + +The BAL tool developed in Geoscience Australia (GA) has been developed +and tested in ArcGIS 10.2. However, GA does not guarantee that the +information derived is totally accurate or complete. Therefore, you +should not solely rely on this information. Key limitations and +approximations include the following: + +* The BAL is produced based on the simplified method (Method 1) in AS + 3959 (2009). When the land downslope is more than 20 degrees, more + detailed method (Method 2) should be adopted. Method 2 has not been + incorporated into the BAL toolbox. Instead, a constant value + of 200 is provided as BAL for such circumstances. + +* Elevation data is a critical input of the tool. Digital Elevation + Model (DEM) with finer resolution usually leads to more accurate BAL + results. The example data uses a DEM with a resolution of 1 second + of arc (approximate 30 m by 30 m grid cell at the equator), the best + available national scale elevation dataset at the time of + modelling. As with all spatial analyses, the results are sensitive + to the input DEM's quality, resolution, coverage and currency and + should therefore be used with this understanding. + +* Vegetation data is another critical input into the tool. Method 1 in + AS 3959 (2009) considers the vegetation up to 100 metres from the + site of interest. Ideally a vegetation dataset with finer resolution + (preferred at metre level) is required to derive sensible BAL + analyses. Where finer vegetation data is not available, the + alternative coarse vegetation data may lead to inaccurate output + BAL. + +* The BAL toolbox is intended to run in the ArcGIS toolbox environment + and is not intended to run in a Python script environment. + +* This software algorithm adapts the Method 1 in AS 3959 (2009) by + modelling it spatially. Readers are assumed to be familiar with AS + 3959 (2009). For the detailed description of the Method 1, please + refer to the `Standard AS 3959 (2009) + `_. + + + + diff --git a/docs/userguide/setup.rst b/docs/userguide/setup.rst new file mode 100644 index 0000000..87f02c7 --- /dev/null +++ b/docs/userguide/setup.rst @@ -0,0 +1,62 @@ +.. _setup: + +====================== +Setting up the toolbox +====================== + +Adding the toolbox into ArcGIS 10.2 +----------------------------------- + +Follow the steps below to add the |project_name| into ArcGIS 10.2: + +* Open the ArcToolbox window. See :numref:`arctoolbox`. + +.. _arctoolbox: + +.. figure:: /docs/images/arctoolbox.jpg + :align: center + :alt: ArcToolbox window. + :figclass: align-center + + The ArcToolbox window. + +* Right click **ArcToolbox** at the top of the window, see + :numref:`rightclickarctoolbox`. + +.. _rightclickarctoolbox: + +.. figure:: /docs/images/rightclick_arctoolbox.jpg + :align: center + :alt: Right click ArcToolbox in the ArcToolbox window. + :figclass: align-center + + Right click **ArcToolbox** in the ArcToolbox window. + +* Select **Add Toolbox...**, a dialog box is open. See :numref:`addtoolboxdialog`. + +.. _addtoolboxdialog: + +.. figure:: /docs/images/addtoolbox_dialog.jpg + :align: center + :alt: Add toolbox dialog window. + :figclass: align-center + + The **Add Toolbox** dialog window. + +* In the dialog box, navigate to the location of the package, for + example :file:`C:\\bal`, you will find the **BAL.tbx**. See :numref:`addtoolboxdialog`. + + +* Select **BAL.tbx** and click **Open**, a new toolbox called **BAL** + is added to the ArcToolbox. See :numref:`baltoolboxloaded`. + +.. _baltoolboxloaded: + +.. figure:: /docs/images/BAL_toolbox.jpg + :align: center + :alt: BAL toolbox is added. + :figclass: align-center + + The **BAL** toolbox is added. + + diff --git a/docs/utilities.rst b/docs/userguide/utilities.rst similarity index 91% rename from docs/utilities.rst rename to docs/userguide/utilities.rst index d87c9bd..7c0d584 100644 --- a/docs/utilities.rst +++ b/docs/userguide/utilities.rst @@ -26,9 +26,10 @@ bal_database.py .. automodule:: bal_database :members: - sa_tools.py -=========================================== +=========== .. automodule:: sa_tools :members: + + diff --git a/docs/userguide/writing_documentation.rst b/docs/userguide/writing_documentation.rst new file mode 100644 index 0000000..51700a4 --- /dev/null +++ b/docs/userguide/writing_documentation.rst @@ -0,0 +1,216 @@ +.. _writing_documentation: + +Writing Documentation +===================== + +The documentation for |project_name| is written using ReSTructured text (.rst) +and the Sphinx documentation builder. + +The best way to learn how to write .rst is to look at the source of existing +documentation - the markup syntax is very simple. +There are a number of useful tags that you can use to make your documentation +clear and visually interesting, those more commonly used in this document are +listed below. +For a more detailed list, please visit the +`Sphinx Inline Markup page `_. + +A complete list of supported .rst markup is also available +`here `_. + +Here are a few tips for documentation writers: + +1. Take a look in the `lookup table <./lookup_table.html>`_ to see which terms + and phrases are used and which you should definitely **not** translate. +#. There is a "Community Edition" of + `PyCharm `_ available. + Consider using this for writing documentation. +#. Try to not write more than **80 Characters in one line**. + That makes the documentation much easier to maintain. +#. Try to create a reference anchor for at least every new heading (page). + If it is useful and important you might also want to put anchors on + subheadings. +#. Try to avoid duplicate target names (anchors). + Always use unique identifiers. + If you are not sure - the longer the name the more unlikely it is already used. +#. Try to use underscores (_) in filenames and links (anchors) as a separator. +#. Try to use dashes (-) in directory names as a separator. +#. Try to avoid using tables wherever possible. + Only use tables if there is really no other way to display the + documentation. +#. If you have to use tables try to avoid using TABS in favour of SPACES. + TABS only confuse the computer while building documentation and leads to + unnecessary errors. + +.. _common_tags: + +Common tags used in the Documentation: +-------------------------------------- + +Here are some useful tags +:: + + |project_name| is currently a substitution for the Project name (Bushfire Attack Level) + Normally, there are no heading levels assigned to certain characters as the + structure is determined from the succession of headings. However, for the + Python documentation, this convention is used, which you may follow: + + # with overline, for parts + * with overline, for chapters + + First two are normaly not used as we usually start with a section. + + =, for sections + -, for subsections + ^, for subsubsections + ", for paragraphs + + Section + ======= + + SubSection + ---------- + + Subsubsection + ............. + + Subsubsubsection (if needed) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + **bold** + + *italics* + + `web link`_ Link to a named external reference + + :ref:`my-reference-label` points to a reference which has to be + implemented like: + + .. _my-reference-label: The anchor for the :ref: needs to be + in front of a Section. + Section to cross-reference Like it is here. + -------------------------- + + :ref:`title ` Same as above except using the Title and + not the referenced headline. + + :doc:`../user-docs/filename` referencing an internal file + + :samp:`flood [m]` A piece of literal text, such as code. + + :menuselection:`Plugins --> Manage Plugins` This is used to mark a complete + sequence of menu selections, + including selecting submenus. + + :guilabel:`OK` Labels presented as part of an interactive user interface + should be marked using guilabel. + + :kbd:`Control-x Control-f` Mark a sequence of keystrokes. + + :command:`rm` (The name of an OS-level command, such as rm.) + + :file:`/etc/fstab` to change something + + .. note:: Note in a little call out box + + .. todo:: Todo item in a call out box + + .. warning:: Much like Note but clearly visible + + There are more markers available: + + .. attention:: + .. caution:: + .. danger:: + .. error:: + .. hint:: + .. important:: + .. tip:: + + .. table:: table title + + ============ ================ + Key Allowed Values + ============ ================ + units m + units wet/dry + units feet + ============ ================ + + +-----------------------+-----------------------+ + | Symbol | Meaning | + +=======================+=======================+ + | .. image:: tent.* | Campground | + +-----------------------+-----------------------+ + | .. image:: waves.* | Lake | + +-----------------------+-----------------------+ + | .. image:: peak.* | Mountain | + +-----------------------+-----------------------+ + + figure and images are easily exchangeable when using * instead of jpg or + png. In that way the Pictures can be exchanged to a new format without + changing the source code. + + .. figure:: picture.* + :scale: 50 % + :alt: map to buried treasure + :figwidth: lenght or percentage of current line width + :figclass: text + + This is the caption of the figure (a simple paragraph). + + .. image:: /static/tutorial/001.* + :height: 100 px + :width: 200 pt + :scale: 50 % + :alt: alternate text + :align: center + +remark: use pt instead of px because of latex output +* A4 = height ~ 1000pt +* A4 = width ~ 700pt + +Help writing/fixing documentation +--------------------------------- + +Helping to write the documentation is an easy task. +The only thing you need to have is a local copy of the |project_name| +documentation branch. + +Clone |project_name| documentation +.................................. + +.. note:: This is a one-time process. You do not need to repeat it - it is + here for reference purposes only. + +In order to help with documentation, you need: + +* A GitHub account +* A fork of the BAL repository (only if you do not have commit access to + the main repository) + +Creating a GitHub account is done by clicking on the :guilabel:`Sign up for free` +button on https://github.com/ and filling out the necessary fields. + +Cloning the documentation of |project_name| is easy; you only have to follow +this procedure: + +.. note:: This documentation assumes that you have the whole |project_name| source + available under :file:`$HOME/dev/python/...` + +Clone your forked github |project_name| documentation by entering following +command:: + + $ git clone https://github.com//bal.git + +Search for the .rst file you'd like to extend/fix and work on it. + +Afterwards commit your local changes to your local clone with the command:: + + $ git commit -a -m "fixed a typo" + +After that you have to push your local changes to your github fork with:: + + $ git push + +You can then do a pull request on github to request your changes be +reviewed and added into the official documentation. diff --git a/docs/veg_example.jpg b/docs/veg_example.jpg deleted file mode 100644 index 2935e0a..0000000 Binary files a/docs/veg_example.jpg and /dev/null differ diff --git a/examples/input/info/arc.dir b/examples/input/info/arc.dir index 74e28ce..0c1f91f 100644 Binary files a/examples/input/info/arc.dir and b/examples/input/info/arc.dir differ diff --git a/index.rst b/index.rst index 0e57eb2..a97f242 100644 --- a/index.rst +++ b/index.rst @@ -1,71 +1,36 @@ -.. BAL documentation master file, created by - sphinx-quickstart on Tue Jul 14 11:29:00 2015. +.. Bushfire Attack Level Toolbox documentation master file, created by + sphinx-quickstart on Wed Apr 12 11:02:21 2017. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Bushfire Attack Level -=============================== - - - +Welcome to Bushfire Attack Level Toolbox's documentation! +========================================================= Overview -=========================================== - - -This toolbox is used to compute the Bushfire Attack Level (BAL) for an area of interest within Australia based on the input vegetation and elevation datasets. - -The computation algorithm is adapted spatially to Method 1 in the Australian Standard AS 3959 (2009)--*Construction of buildings in bushfire-prone areas*. - -The output contains eight raster files that represent the BAL for each of eight cardinal directions and an extra raster file that represents the maximum BAL of the eight directions for each grid cell. +-------- +This toolbox is used to compute the Bushfire Attack Level (BAL) for an +area of interest within Australia based on the input vegetation and +elevation datasets. -Disclaimer -========== -.. toctree:: - :maxdepth: 1 - - Disclaimer - +The computation algorithm is adapted spatially to Method 1 in the +Australian Standard AS 3959 (2009)--*Construction of buildings in +bushfire-prone areas*. -Introduction -============ .. toctree:: :maxdepth: 1 + :caption: Contents - Introduction - Background - - -How to use the toolbox -====================== -.. toctree:: - :maxdepth: 1 - - Installation - Setting up the toolbox - Running the toolbox - Examples - - -Code documentation -================== - -This part is extracted from the source code in-line documentation and included in this document for the completeness of the software package. It does not directly instruct users how to use the toolbox to calculate the BAL. Instead, it might be useful for software engineers or developers to review the source code and maintain or upgrade it in the future. - -.. toctree:: - :maxdepth: 2 - - docs/bal - docs/calculate_bal - docs/utilities - - -References -========== - -AS 3959, 2009. Construction of buildings in bushfire-prone areas, Australian Standard + docs/disclaim + docs/userguide/index + docs/training/index + docs/acknowledgements +Indices and tables +------------------ +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`