Documentation

* updated minimally
* html built

docs/_build/html/_modules/index.html

@@ -147,7 +147,8 @@
   <h1>All modules for which code is available</h1>
 <ul><li><a href="UserList.html">UserList</a></li>
 <li><a href="ahds.html">ahds</a></li>
-<ul><li><a href="ahds/data_stream.html">ahds.data_stream</a></li>
+<ul><li><a href="ahds/core.html">ahds.core</a></li>
+<li><a href="ahds/data_stream.html">ahds.data_stream</a></li>
 <li><a href="ahds/grammar.html">ahds.grammar</a></li>
 <li><a href="ahds/header.html">ahds.header</a></li>
 </ul></ul>

docs/_build/html/index.html

@@ -156,8 +156,9 @@ <h1><code class="docutils literal notranslate"><span class="pre">ahds</span></co
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="overview.html"><code class="docutils literal notranslate"><span class="pre">ahds</span></code></a><ul>
 <li class="toctree-l2"><a class="reference internal" href="overview.html#overview">Overview</a></li>
-<li class="toctree-l2"><a class="reference internal" href="overview.html#installation">Installation</a></li>
 <li class="toctree-l2"><a class="reference internal" href="overview.html#license">License</a></li>
+<li class="toctree-l2"><a class="reference internal" href="overview.html#installation">Installation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="overview.html#getting-started">Getting Started</a></li>
 <li class="toctree-l2"><a class="reference internal" href="overview.html#future-plans">Future Plans</a></li>
 <li class="toctree-l2"><a class="reference internal" href="overview.html#background-and-definitions">Background and Definitions</a></li>
 <li class="toctree-l2"><a class="reference internal" href="overview.html#ahds-modules"><code class="docutils literal notranslate"><span class="pre">ahds</span></code> Modules</a></li>

docs/overview.rst

@@ -12,12 +12,35 @@
 Overview
 ----------------------------------------------
 ``ahds`` is a Python package to parse and handle Amira (R) files.
-It was developed to facilitate reading of Amira (R) files as part of the EMDB-SFF toolkit.
+It was developed to facilitate reading of Amira (R) files as part of the `EMDB-SFF toolkit <https://sfftk.readthedocs.io>`_.
 
 .. note::
 
     Amira (R) is a trademark of Thermo Fisher Scientific. This package is in no way affiliated with with Thermo Fisher Scientific.
 
+----------------------------------------------
+License
+----------------------------------------------
+
+``ahds`` is free software and is provided under the terms of the Apache License, Version 2.0.
+
+::
+
+    Copyright 2017 EMBL - European Bioinformatics Institute
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+    either express or implied. See the License for the specific
+    language governing permissions and limitations under the License.
+
+
 Use Cases
 ==============================================
 *     Detect and parse Amira (R) headers and return structured data
@@ -26,43 +49,197 @@ Use Cases
 
 *     Easy extensibility to handle previously unencountered data streams
 
-``ahds`` was written and is maintained by Paul K. Korir.
+``ahds`` was written and is maintained by Paul K. Korir but there is
+`a list of contributors <https://github.com/emdb-empiar/ahds/blob/dev/CONTRIBUTORS.txt>`_.
+Feel free to join this initiative.
 
 --------------------------------------------
 Installation
 --------------------------------------------
-Presently, ``ahds`` only works with Python 2.7 but will soon work on Python 3. Please begin by 
-installing ``numpy<1.16`` using 
+``ahds`` works with Python 2.7, 3.5, 3.6 and 3.7. It requires ``numpy`` to build.
 
 ::
 
-    pip install numpy<1.16
+    pip install numpy
 
-because it is needed to run ``setup.py``. Afterwards you may run
+Afterwards you may run
 
 ::
 
     pip install ahds
 
-----------------------------------------------
-License
-----------------------------------------------
+.. todo::
 
-::
+    Figure out a way to avoid the need for ``numpy`` as part of the build.
 
-    Copyright 2017 EMBL - European Bioinformatics Institute
-                        
-    Licensed under the Apache License, Version 2.0 (the "License"); 
-    you may not use this file except in compliance with the License. 
-    You may obtain a copy of the License at 
-    
-    http://www.apache.org/licenses/LICENSE-2.0
-                        
-    Unless required by applicable law or agreed to in writing, 
-    software distributed under the License is distributed on an 
-    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, 
-    either express or implied. See the License for the specific 
-    language governing permissions and limitations under the License.     
+--------------------------------------------
+Getting Started
+--------------------------------------------
+
+You can begin playing with ``ahds`` out of the box using the provided console command ``ahds``.
+
+
+.. code:: bash
+
+    me@home ~$ ahds ahds/data/FieldOnTetraMesh.am
+    ********************************************************************************************************************************************
+    AMIRA (R) HEADER AND DATA STREAMS
+    --------------------------------------------------------------------------------------------------------------------------------------------
+    +-ahds/data/FieldOnTetraMesh.am                                                                  AmiraFile [is_parent? True ]
+    |  +-meta                                                                                            Block [is_parent? False]
+    |  |  +-file: ahds/data/FieldOnTetraMesh.am
+    |  |  +-header_length: 182
+    |  |  +-data_streams: 1
+    |  |  +-streams_loaded: False
+    |  +-header                                                                                    AmiraHeader [is_parent? True ]
+    |  |  +-filetype: AmiraMesh
+    |  |  +-dimension: 3D
+    |  |  +-format: BINARY
+    |  |  +-endian: BIG
+    |  |  +-version: 2.0
+    |  |  +-extra_format: None
+    |  |  +-Parameters                                                                                   Block [is_parent? False]
+    |  |  +-Tetrahedra                                                                                   Block [is_parent? False]
+    |  |  |  +-length: 23685
+    |  +-data_streams                                                                                    Block [is_parent? False]
+    ********************************************************************************************************************************************
+
+The ``ahds`` command takes the following arguments
+
+.. code:: bash
+
+    me@home ~$ ahds -h
+    usage: ahds [-h] [-s] [-d] [-l] file [file ...]
+
+    Python tool to read and display Amira files
+
+    positional arguments:
+      file                a valid Amira file with an optional block path
+
+    optional arguments:
+      -h, --help          show this help message and exit
+      -s, --load-streams  whether to load data streams or not [default: False]
+      -d, --debug         display debugging information [default: False]
+      -l, --literal       display the literal header [default: False]
+
+You can specify a **dotted path** after the filename to only render that the content of that field in the header:
+
+.. code:: bash
+
+    me@home ~$ ahds ahds/data/FieldOnTetraMesh.am header
+    ***********************************************************************************************************************************
+    ahds: Displaying path 'header'
+    -----------------------------------------------------------------------------------------------------------------------------------
+    +-header                                                                                       AmiraHeader [is_parent? True ]
+    |  +-filetype: AmiraMesh
+    |  +-dimension: 3D
+    |  +-format: BINARY
+    |  +-endian: BIG
+    |  +-version: 2.0
+    |  +-extra_format: None
+    |  +-Parameters                                                                                      Block [is_parent? False]
+    |  +-Tetrahedra                                                                                      Block [is_parent? False]
+    |  |  +-length: 23685
+
+
+For debugging you can display the literal header (the exact header present in the file) using the ``-l/--literal`` flag.
+Also, you can display the parsed data structure using the ``-d/--debug`` flag.
+
+.. code:: bash
+
+    me@home ~$ ahds --literal --debug ahds/data/FieldOnTetraMesh.am
+    ***********************************************************************************************************************************
+    ahds: Displaying literal header
+    -----------------------------------------------------------------------------------------------------------------------------------
+    # AmiraMesh 3D BINARY 2.0
+    # CreationDate: Tue Nov  2 11:46:31 2004
+
+
+    nTetrahedra 23685
+
+    TetrahedronData { float[3] Data } @1
+    Field { float[3] f } Constant(@1)
+
+    # Data section follows
+    ***********************************************************************************************************************************
+    ahds: Displaying parsed header data
+    -----------------------------------------------------------------------------------------------------------------------------------
+    [{'designation': {'dimension': '3D',
+                      'filetype': 'AmiraMesh',
+                      'format': 'BINARY',
+                      'version': '2.0'}},
+     {'comment': {'date': 'Tue Nov  2 11:46:31 2004'}},
+     {'array_declarations': [{'array_dimension': 23685,
+                              'array_name': 'Tetrahedra'}]},
+     {'data_definitions': [{'array_reference': 'Tetrahedra',
+                            'data_dimension': 3,
+                            'data_index': 1,
+                            'data_name': 'Data',
+                            'data_type': 'float'},
+                           {'array_reference': 'Field',
+                            'data_dimension': 3,
+                            'data_index': 1,
+                            'data_name': 'f',
+                            'data_type': 'float',
+                            'interpolation_method': 'Constant'}]}]
+
+    ********************************************************************************************************************************************
+    AMIRA (R) HEADER AND DATA STREAMS
+    --------------------------------------------------------------------------------------------------------------------------------------------
+    +-ahds/data/FieldOnTetraMesh.am                                                                  AmiraFile [is_parent? True ]
+    |  +-meta                                                                                            Block [is_parent? False]
+    |  |  +-file: ahds/data/FieldOnTetraMesh.am
+    |  |  +-header_length: 182
+    |  |  +-data_streams: 1
+    |  |  +-streams_loaded: False
+    |  +-header                                                                                    AmiraHeader [is_parent? True ]
+    |  |  +-filetype: AmiraMesh
+    |  |  +-dimension: 3D
+    |  |  +-format: BINARY
+    |  |  +-endian: BIG
+    |  |  +-version: 2.0
+    |  |  +-extra_format: None
+    |  |  +-Parameters                                                                                   Block [is_parent? False]
+    |  |  +-Tetrahedra                                                                                   Block [is_parent? False]
+    |  |  |  +-length: 23685
+    |  +-data_streams                                                                                    Block [is_parent? False]
+    ********************************************************************************************************************************************
+
+By default, data streams are not read --- only the header is parsed. You may obtain the data streams using the
+``-s/--load-streams`` flag.
+
+.. code:: bash
+
+    me@home ~$ ahds --load-streams ahds/data/FieldOnTetraMesh.am
+    ********************************************************************************************************************************************
+    AMIRA (R) HEADER AND DATA STREAMS
+    --------------------------------------------------------------------------------------------------------------------------------------------
+    +-ahds/data/FieldOnTetraMesh.am                                                                  AmiraFile [is_parent? True ]
+    |  +-meta                                                                                            Block [is_parent? False]
+    |  |  +-file: ahds/data/FieldOnTetraMesh.am
+    |  |  +-header_length: 182
+    |  |  +-data_streams: 1
+    |  |  +-streams_loaded: True
+    |  +-header                                                                                    AmiraHeader [is_parent? True ]
+    |  |  +-filetype: AmiraMesh
+    |  |  +-dimension: 3D
+    |  |  +-format: BINARY
+    |  |  +-endian: BIG
+    |  |  +-version: 2.0
+    |  |  +-extra_format: None
+    |  |  +-Parameters                                                                                   Block [is_parent? False]
+    |  |  +-Tetrahedra                                                                                   Block [is_parent? False]
+    |  |  |  +-length: 23685
+    |  +-data_streams                                                                                    Block [is_parent? True ]
+    |  |  +-Data                                                                           AmiraMeshDataStream [is_parent? False]
+    |  |  |  +-data_index: 1
+    |  |  |  +-dimension: 3
+    |  |  |  +-type: float
+    |  |  |  +-interpolation_method: None
+    |  |  |  +-shape: 23685
+    |  |  |  +-format: None
+    |  |  |  +-data: [  0.8917308   0.9711809 300.       ],...,[  1.4390504   1.1243758 300.       ]
+    ********************************************************************************************************************************************
 
 ----------------------------------------------
 Future Plans
@@ -74,7 +251,7 @@ Background and Definitions
 ----------------------------------------------
 ``ahds`` presently handles two types of Amira (R) files:
 
-*     `AmiraMesh` files, which typically but not necessarily have a ``.am`` extension, and
+*     `AmiraMesh` files, which typically but not necessarily have a ``.am``, ``.elm``, ``.lmb`` extension, and
 
 *     `HyperSurface` files, which have ``.surf`` and represent an older filetype.
 
@@ -84,9 +261,12 @@ Both file types consist of two parts:
 
 *     one or more `data streams`. 
 
-Headers are structured in a modified VRML-like syntax and differ between AmiraMesh and HyperSurface files in some of the keywords used. 
+Headers are structured in a modified VRML-like syntax and differ between AmiraMesh and HyperSurface files in some of
+the keywords used.
 
-A data stream is a sequence of encoded bytes either referred to in the header by some delimiter (usually ``@<data_stream_index>``, where ``<data_stream_index>`` is an integer) or a set of structural keywords (e.g. ``Vertices``, ``Patches``) expected in a predefined sequence.
+A data stream is a sequence of encoded bytes either referred to in the header by some delimiter
+(usually ``@<data_stream_index>``, where ``<data_stream_index>`` is an integer) or a set of structural keywords
+(e.g. ``Vertices``, ``Patches``) expected in a predefined sequence.
 
 Headers in Detail
 ==============================================