========
shellRpt
========



.. contents:: Table of Contents
   :backlinks: top


------------
Introduction
------------


Creates a Comma Delimited (CSV) file of characteristics of all solids
and surfaces (shells) in a geometry object or from all geometry objects
in a directory. 


-----------
Quick Start
-----------
            
Create a comma delimited (CSV) report listing various characteristics
from all solids/surfaces in an object or all solids/surfaces in all
objects in a directory.

Note: If run outside of a MineSight(R) project directory the 
materials folder may not be found. Therefore, the script will be
unable to find material attributes. 

           
INI Setup
---------
        
The ini file is named shellRpt.ini, and must contain the following:

  INPUT_PATH=D:\\work\\polyRpt\\trueThickness\\_MSRESOURCES\\geology\\ew25 true new

    The input path can be a directory path or an msr file path.  If it
    is a directory, all msr objects in that directory are processed. If
    it is an msr file path, only that msr is processed.  The value
    assigned to INPUT_PATH is not surrounded by quotes and is the
    absolute path. The componets in the path can be separated by double
    backslashes (\\) or single front-slashes (/). 
           
  OUTPUT_RPT_PATH=shellRpt.csv

    The output report file path can be an absolute path or just the file
    name, in which case it is written to the current directory.  This is
    a comma delimited report and the file name should end with .csv do
    the default spawning program, like Excel can display it.        
           
               
  RPT (Report) Configuration Values:

  All constants starting with RPT\_ are set to boolean values to indicate
  what is to be included in the report.

  Set to zero to not report or one to report.

  All tokens need to be present in the ini file.
               
  The order of these lines in the ini file reflect the order of the
  columns in the report. 

  The following setting (ini lines) will report all the available
  information for each feature and indicate the order it is reported in
  the spreadsheet (CSV file).

  ::
           
     RPT_RESOURCE_NAME=1
     RPT_RESOURCE_MATERIAL=1
     RPT_ELEMENT_NAME=1
     RPT_ELEMENT_MATERIAL=1
    

Notes
-----
     
The element material model code is what is used for coding the model.
If msr material has a different model code this would be a strange way
to set up the model.

The material vbm code for a shell can be important if the shell is
sliced into 2d polygons, so this option is be included in report.


----------
Discussion
----------

Creates a csv file of characteristics of all solids and surfaces
(shells) in a geometry object or from all geometry objects in a
directory. 


Items to include in the report are user selected and can be configured
as to which column an item is written to in the comma delimited report.

The selection of solids and surfaces to include in the report can also
be filtered by volume, name and material.

The desired configuration can be saved to an .ini file for future runs
or entered in the interface panel in interactive mode.

For detailed help, place mouse in desired area of interface panel and
press F1.  
 
    ==========================  ======================================
    Reporting Items             Description
    ==========================  ======================================    
    Resource Folder             Name of folder where geometry object resides
    Resource name               Name of .msr file/geometry object
    Element name                Solid/surface element attributed name 
    Resource material           Geometry object material
    Element material            Solid/surface attributed material
    Resource model code         Object material model code
    Element model code          Solid/surface material model code
    Resource VBM code           Object material VBM code
    Element VBM code            Solid/surface material VBM code
    Volume cu meters            Volume of the solid in cu meters
    Volume cu feet              Volume of the solid in cu feet
    Volume cu yards             Volume of the solid in cu yards
    Surface area sq meters      Area in square meters
    Surface area hectares       Area in hectares
    Surface area sq feet        Area in square feet
    Surface area sq yards       Area in square yards
    Surface area acres          Area in acres
    Total faces                 Number of faces of the solid/surface
    Total points                Number of nodes of the solid/surface 
    Tonnage                     Computed tonnage of the solid
    Tonnage SG                  Specific gravity used to compute tonnage
    Tonnage TF                  Tonnage factor used to compute tonnage
    ==========================  ======================================
       

----------------------
How to Run this Script
----------------------

This script can be run from MineSight(R) or from the command line. It
can be run with or without the GUI interface.
    
If run from MineSight(R) or from the command line with no arguments, a
GUI is presented.  If run from MineSight(R), no arguments are allowed,
so the GUI panel is always presented.

To run silent without the GUI, an .ini file can be used that contains
configuration values describing what is wanted in the report.  Starting
the script with command line arguments as explained below suppress the
GUI interface panel and the values .ini file are used. 

To create an .ini file, run the script with no arguments and enter your
desired configuration into the GUI panel and check "Save Responses".
This will create an .ini file in your project directory, if run from
MineSight(R) or the working directory, if run from the command line.

Multiple .ini files can be created, one for each project as they can be
stored in the respective project directories.

The .ini file is always named :file:`<script name>.ini`.
    
    Ex: :file:`shellRpt.ini`

    ::

           Arguments (if running from cmd line):           
           --------- 
            1       - Do not present GUI.
                      Use config values from .ini file
                      exclusively, and fail if .ini
                      values are incorrect or if .ini
                      file does not exist.
            2       - Do not present GUI.
                      Try and use .ini values. If no .ini
                      file or if .ini values are
                      incorrect, try to use default
                      values coded inside this
                      script below in the
                      == START CONFIGURATION OPTIONS ===
                      section.
            0[none] - Always present GUI.
                      Use .ini values to populate panel. If no .ini file
                      exists, or incorrect values in .ini file, reset to allow
                      user to specify desired setup from GUI panel.

            Example:
            
                      C:> shellRpt.py 1

------------------
A Note about Speed
------------------

The more you filter the data selection, the faster the script will run.

For example, if you only want only solids, select "Use closed solids
only" or filter by volume > 0.0.
        
Computing volume is the most time consuming feature of this script. This
is because an external call to the union.exe standalone engine is made.
Eventually, an API between Grail and the standalone engines will be
developed that will eliminate the need for the external call and will
greatly speed things up.                     


------------------
Command Line Usage
------------------

::

  Usage: shellRpt.py ['' | 0 | 1 | 2]
      
        where
        
        ''|0   Present graphical user interface panel using values
               retrieved from .ini file, if any. Reset any bad .ini values
               before presenting GUI or use default internal values
               to populate panel if no .ini file.
               (default mode from MS3D)
            1  Silent: Use .ini values exclusively.
               Do not present gui. Fail if bad .ini values.
            2  Silent: Use default(internal) values if no .ini/bad .ini values.
               Do not present gui. Fail if bad internal config values.    

-------
Dialog
-------

Presents GUI when run without any arguments.  The following values are
available in the panel.


Input directory or Input Object
-------------------------------    

Specify either an input directory containing geometry objects or an
input geometry object by checking the radio buttons. Then enter or
browse for the directory path or msr file path containing the solids or
surfaces.
     
If a directory is specified, all geometry objects in that directory will
be inspected for solids/surfaces.  If a single object is specified, all
solids/surfaces within that object are selected.
 
Recurse subdirectories
----------------------
    
If Input directory is selected above, you have the option to recursively
include all geometry objects in its subdirectories, if checked.
    
Project Units
-------------
Select the measurement units for the solids and
surfaces as either metric or imperial.   
    

 
Filter the Selection of Solids/Surfaces
---------------------------------------

The selection of solids and surfaces to be processed can be controlled
by filtering them by various charicteristics:

Filter by element name
......................


If you want only elements that are attributed with a certain name value,
check the box and enter the value for the name in the entry box.  Only
elements matching that name value will be included in the report.

.. Note::
   'Filter by element name' can be   checked and the name left blank.
   This will select all elements that do not have an attributed name.

Filter by element material
..........................
    
If you want only elements that are attributed with a certain material,
check the box and enter the value for material in the entry box.  Only
elements attributed with that material or unattributed elements who's
resource is attributed with that material value will be included in the
report.

.. Note::
   Elements that do not have an attributed material inherit the material
   of the object they are in. So, there essentially are no elements
   without a material. Therefore, if 'Filter by element material' is
   checked, a value must be entered in the entry box; it can not be
   blank.


Filter by resource material
............................


If you want only elements from resource objects with a certain material,
check the box and enter the value for material in the entry box.  Only
object that are attributed with that material value will be scanned for
solids/ surfaces to be processed. All resource objects have a material,
even if it is only the default material.  Therefore, if 'Filter by
resource material' is checked, a value must be entered in the entry box;
it can not be blank.
    
Use closed solids only
......................

Solids have no openings and are essentially closed surfaces. If you only
want solids included in the report, check the box 'Use closed solids
only' or filter by volume greater than zero below. 

Filter by volume
................

Only solids have volume, surfaces do not because they are not closed. If
you want only solids greater than a certain value included in the
report, check the 'Filter by volume >' checkbox and enter a "greater
than" value in cu meters or cu yards. Only solids that have a volume
greater than the value entered will be included in the report.      
    

Report Output
-------------

Report Comma Delimited File (CSV) File
......................................

Enter or browse for the output report file, which is normally a .csv
file. (comma delimited).  The path can be an absolute path or just the
file name, in which case it is written to the current directory.

Show a Comma Delimited File (CSV) Report
........................................
    
Check if you want the report to be automatically spawned by its default
associated application, usually Excel for .csv files and Notepad for
.txt files.     

    
Compute Tonnage
............... 

Check this box if you want tonnage computed for each solid.

Make sure that you also include the field "Tonnage" in the "Report
Items" list.

Select the SG (Specific Gravity) radio button and enter the specific
gravity value that you wish to use to compute tonnages.

     - or -
    
Select the TF (Tonnage Factor) radio button and enter the tonnage factor
value that you wish to use to compute tonnages.
    

-----------------------
Selecting Report Fields
-----------------------
     
This section allows the selection of items to be included in the report
and which column that value will be placed into in the comma delimited
report. 


To Select which Items to Report
-------------------------------
    
From the list of 'Available Items:', highlight those fields wanted in
the report and click the 'move right' arrow to move them into the
'Report Items:' column.

Alternatively, to remove fields not wanted in the report, highlight
those fields in the 'Report Items:' column and click the 'move left'
arrow to remove them from the list.

To Select which Column to Place the Values
------------------------------------------

The position of the fields in the 'Report Items:' column represents the
order of the fields on each row of the report. For example, if "Tonnage"
is the first item in the 'Report Items:' box, it will be the first
column of each row in the report.

To move items to the positions desired, use the arrows to the right of
the 'Report Items:' box to reposition the items to 'top', 'up one',
'down one' and to the 'bottom' of the list.


Available Items to Report
-------------------------

    "Resource folder"

        Parent folder where geometry object resides.

    "Resource name"

        Resource name is the name of the geometry object (.msr file
        name).

    "Resource material"

        Resource material is the material assigned to the resource
        object (.msr).

    "Resource model code"

        Resource model code is the model code assigned to the resource
        object material.

    "Resource vbm code"

        Resource vbm code is the vbm code assigned to the resource
        object's material.   

    "Element name"

        Element name is the attributed name of the polygon or polyline
        element.

    "Element material"

        Element materail is the attributed material of the polygon or
        polyline. If the element has no name, it inherits the material
        of its resource object.

    "Element model code"   

        Element model code is the model code of the polygon or polyline
        material.
        
    "Element vbm code"

        Element vbm code is the vbm code of the polygon or polyline
        material.


    "Total faces"

        Total faces is the number of faces in the face list.
        
    "Total points"

        Total points is the number of nodes (points) in the
        solid/surface. 
        
    "Surface area sq meters"

        The area in square meters of all the faces.  

    "Surface area hectares"

        The area in hectares of all the faces.

    "Surface area sq feet"

        The area in square feet of all the faces.    
    
    "Surface area sq yards"

        The area in square yards of all the faces. 
        
    "Surface area acres"

        The area in acres of all the faces. 

    "Volume cu meters"

        The volume of the solid in cubic meters. Surfaces do not have
        volumes because the are not closed.
        
    "Volume cu feet"

        The volume of the solid in cubic feet.  Surfaces do not have
        volumes because the are not closed.

    "Volume cu yards"

        The volume of the solid in cubic yards.  Surfaces do not have
        volumes because the are not closed.

    "Tonnage"

        The tonnage of the solid in cubic yards. Surfaces do not have
        volumes because the are not closed.  
    
----------------
Saving Responses
----------------   

If "Save Responses" is checked, a configuration (.ini) file is created
in the current directory containing the information entered in the
panel. These values are used to populate the panel the next time the
script is run.

The .ini file is always named poly2dRpt.ini or the name of this script
with a .ini extension.

As long as "Save Responses" is checked, the .ini file will be rewritten
after each run.

If no .ini file exists, the panel is populated from internal values
stored in the script itself to be used as default values.

If the script is run in silent mode, the values in the .ini file are
used for the run.  If there is no .ini file, the default values internal
to the script are used.
    
(See General Help by pressing F1 in any area outside boxes in the panel
for mode info.)  
    

-------------------------------
Configuration (.ini) File Setup
-------------------------------
    
The .ini file is simply an ASCII file formatted as in the following
example. All items beginning with RPT\_ are the reporting fields. If set
equal to one (1), that item is reported and if set equal to zero (0),
that item is not reported. The position of the RPT\_ items in the .ini
file indicates the column position in the report.

The other fields in the .ini file are used to configure the processing
and I/O of the script. 
    

Example .ini File
-----------------

 ::

            INPUT_TYPE=1
            INPUT_DIR_PATH=D:\\work\\shellRpt\\shellObjects
            INPUT_FLN_PATH=D:\\work\\shellRpt\\shellObjects\\TopoSurf.msr
            PROJECT_UNITS=imperial
            FILTER_BY_ELEMENT_NAME=1
            ELEMENT_NAME=
            FILTER_BY_ELEMENT_MATERIAL=0
            ELEMENT_MATERIAL=
            FILTER_BY_RESOURCE_MATERIAL=0
            RESOURCE_MATERIAL=
            USE_CLOSED_SOLIDS_ONLY=1
            FILTER_BY_VOLUME=1
            FILTER_BY_CU_METERS=1
            CU_METERS=1e+016
            FILTER_BY_CU_YARDS=0
            CU_YARDS=0.0
            OUTPUT_FLN_PATH=shellRpt.csv
            SPAWN_RPT=1
            PRINT_TOTALS=1
            COMPUTE_TONNAGE=1
            COMPUTE_TONNAGE_SG=0
            SPECIFIC_GRAVITY=
            COMPUTE_TONNAGE_TF=1
            TONNAGE_FACTOR=0.37
            RPT_RESOURCE_FOLDER=1
            RPT_RESOURCE_NAME=1
            RPT_SURFACE_AREA_SQ_METERS=1
            RPT_SURFACE_AREA_HECTARES=1
            RPT_SURFACE_AREA_SQ_FEET=1
            RPT_SURFACE_AREA_SQ_YARDS=1
            RPT_SURFACE_AREA_ACRES=1
            RPT_VOLUME_CU_METERS=1
            RPT_VOLUME_CU_FEET=1
            RPT_VOLUME_CU_YARDS=1
            RPT_TONNAGE=1
            RPT_ELEMENT_NAME=1
            RPT_RESOURCE_MATERIAL=0
            RPT_RESOURCE_MODEL_CODE=0
            RPT_RESOURCE_VBM_CODE=0
            RPT_ELEMENT_MATERIAL=0
            RPT_ELEMENT_MODEL_CODE=0
            RPT_ELEMENT_VBM_CODE=0
            RPT_TOTAL_FACES=0
            RPT_TOTAL_POINTS=0
            RPT_TONNAGE_SG=0
            RPT_TONNAGE_TF=0

           
Configuration (.ini) Values
---------------------------

    INPUT_TYPE=1

        Integer.
        Set INPUT_TYPE=1 for directory as input
        Set INPUT_TYPE=2 for .msr object as input

    INPUT_DIR_PATH=D:\\work\\shellRpt\\shellObjects

        String. If INPUT_TYPE=1, set INPUT_DIR_PATH to the absolute path
        of the directory to search for objects containing
        solids/surfaces.  Leave unset if inputting only one .msr file:

           INPUT_DIR_PATH=
    
    RECURSE_SUB_DIRECTORIES=1

        Boolean. If equal to one, and INPUT_TYPE is equal to one, all
        directories under INPUT_DIR_PATH will be recursively searched
        for solids/surfaces. If equal to zero, only geometry objects
        from INPUT_DIR_PATH will be included in the report.  

    INPUT_FLN_PATH=D:\\mproject\\_MSRESOURCES\shells.msr

        String. If INPUT_TYPE=2, set INPUT_FLN_PATH to the absolute path
        of the resource or msr file.  Leave unset if inputting an entire
        directory:     
           
           INPUT_FLN_PATH=

        .. Note::

           The values assigned to INPUT_FLN_PATH and INPUT_DIR_PATH are
           not surrounded by quotes and are absolute paths.

           The components in the path can be separated by double
           backslashes (\) or single front-slashes (/). 
           
    OUTPUT_FLN_PATH=shellRpt.csv

        String. The output report file path can be an absolute path or
        just the file name, in which case it is written to the current
        or project directory. The report written to the output file is
        nomally comma delimited and as such the file name should end
        with .csv to be spawed by the default spawning program, usually
        Excel.

        However, if using another extension, such as .txt is used, the
        report will be displayed by the associated application for .txt
        files, such as Notepad.
               
    PROJECT_UNITS=imperial

        String.  PROJECT_UNITS can be set to either imperial or metric.

    SPAWN_REPORT=1

        Boolean. Set SPAWN_REPORT equal to 1 if you want the application
        associated with report file extension, (usually .csv files are
        associated with Excel) to be shown thus displaying the
        report.csv file after it is created by this script.  Set to 0
        (zero) to not show the report.          

    PRINT_TOTALS=1

        Boolean. Writes an line at the end of the .csv file with totals
        for each colume. Set PRINT_TOTALS=1 to include the totals line
        or set PRINT_TOTALS=0 to exclude the totals line.w
               
    FILTER_BY_ELEMENT_NAME=1

        Boolean. Set FILTER_BY_ELEMENT_NAME=1 to only report shells with
        element name equal to ELEMENT_NAME. Set to zero to not filter by
        element name.

    ELEMENT_NAME=c1

        String. If FILTER_BY_ELEMENT_NAME=1, set ELEMENT_NAME equal to
        the name to filter all shells on.

    FILTER_BY_ELEMENT_MATERIAL=1

        Boolean. Set FILTER_BY_ELEMENT_MATERIAL=1 to only report shells
        with material equal to ELEMENT_MATERIAL. Set to zero to not
        filter by element material.

    ELEMENT_MATERIAL=ColorOrange

        String. If FILTER_BY_ELEMENT_MATERIAL=1, set ELEMENT_MATERIAL
        equal to the material to filter all shells on.
        
    FILTER_BY_RESOURCE_MATERIAL=1

        Boolean. Set FILTER_BY_RESOURCE_MATERIAL=1 to only report shells
        with material equal to RESOURCE_MATERIAL. Set to zero to not
        filter by element material.

    RESOURCE_MATERIAL=ColorOrange

        String. If FILTER_BY_ELEMENT_MATERIAL=1, set ELEMENT_MATERIAL
        equal to the material to filter all shells on.

    USE_CLOSED_SOLIDS_ONLY=1

        Boolean. Set USE_CLOSED_SOLIDS_ONLY=1 to only report solids
        (closed surfaces).  Set USE_CLOSED_SOLIDS_ONLY=0 to include all
        solids and surfaces.
        
    FILTER_BY_VOLUME=1

        Boolean. Set FILTER_BY_VOLUME=1 to only report solids (closed
        surfaces) with volume greater than either values below used
        in filter by cu meters or filter by cu yards. 

    FILTER_BY_CU_METERS=1

        Boolean. If FILTER_BY_VOLUME=1, set FILTER_BY_CU_METERS=1 and
        enter the value for CU_METERS to include only solids having a
        volume greater than the amount specified in CU_METERS.
        
    CU_METERS=1016.0

        Real. Value used to include any solid with a volume greater than
        this volume if filtering by cu meters.

    FILTER_BY_CU_YARDS=0

        Boolean. If FILTER_BY_VOLUME=1, set FILTER_BY_CU_YARDS=1 and
        enter the value for CU_YARDS to include only solids having a
        volume greater than the amount specified in CU_YARDS.
        
    CU_YARDS=0.0

        Real. Value used to include any solid with a volume greater than
        this volume if filtering by cu yards.


Reporting Items and Position in Comma Delimited Report (CVS) Report
-------------------------------------------------------------------

All constants starting with RPT\_ are set to boolean values to indicate
what items to include in the report. Set to zero to not report or one to
report.

All tokens need to be present in the ini file.
               
The order of these lines in the ini file reflects the order of the
columns in the report. For example if the resource name is wanted in col
one of the csv report, put RPT_RESOURCE_NAME=1 as the first item in the
list.

        Reporting items:

        ::
        
            RPT_RESOURCE_FOLDER=1
            RPT_RESOURCE_NAME=1
            RPT_SURFACE_AREA_SQ_METERS=1
            RPT_SURFACE_AREA_HECTARES=1
            RPT_SURFACE_AREA_SQ_FEET=1
            RPT_SURFACE_AREA_SQ_YARDS=1
            RPT_SURFACE_AREA_ACRES=1
            RPT_VOLUME_CU_METERS=1
            RPT_VOLUME_CU_FEET=1
            RPT_VOLUME_CU_YARDS=1
            RPT_TONNAGE=1
            RPT_ELEMENT_NAME=1
            RPT_RESOURCE_MATERIAL=0
            RPT_RESOURCE_MODEL_CODE=0
            RPT_RESOURCE_VBM_CODE=0
            RPT_ELEMENT_MATERIAL=0
            RPT_ELEMENT_MODEL_CODE=0
            RPT_ELEMENT_VBM_CODE=0
            RPT_TOTAL_FACES=0
            RPT_TOTAL_POINTS=0
            RPT_TONNAGE_SG=0
            RPT_TONNAGE_TF=0   
   
------------
Dependencies
------------

::

  Python: 2.2.[3-*]
  MineSight 3D: 4.00.*
  MineSight Grail: 4.00.*
  StandaloneEngines (union.exe & dlls) must be in your path

----------------
Revision History
----------------

02.01.2007, 4.00, REF#6991
 - Original

-----------------
License Agreement
-----------------

The Original Code is shellRpt.py.

The Initial Developer of the Original Code is Leica Geosystems.
Portions created by Leica Geosystems are Copyright (C) 2014 year.
Leica Geosystems. All Rights Reserved.