==============
createPartials
==============

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

----------------
Revision History
----------------
.. If this is updated, please also update new.rst in the createPartials_doc directory

**29-Dec-2005:**

    - Original script: partialsFromDir.py (distributed on request script)
    
**01-Apr-2007 RFE# 7309:**

    - Add Long Haul
    
**18-Aug-2007 RFE# 7731:**

    - Add mstype functionality (filter by shell)
    - Remove isgeometry because it loads the whole object (time saver)
    - Various time savings changes
    - Add ability to name partials files from GUI with Wildcards
    - Add choice to use closed shells only
    - Add checkbox to make target dir the same as source dir (orig request from MHT)
    - Add Audit report option, and to spawn with Notepad also
    - Add fixed font to Progress box in GUI and made report clearer 
    - Add disable all widgets with RUN is pushed
    - Add enable all widgets when report is done
    - Above changes required redesign of gui
    - Above changes also required adding new ini values
    - Do some very fancy doc that you are reading now
    - Add workaround for bug where (1st bring up) of ms3d, cwd is not prj dir:
      This allowed prj dir to be initial dir for browsing pcf file and
      prj._msresources to be initial dir for browsing input dir.
    - Sent .pyc (under old name) to MHT to test Aug/27/2007
    - Change name to createPartials because only the .pyc will be distributed so,
      need a new name for those who have old partialsFromDir.py
      script, so this .pyc does not get rewritten if they make
      changes to their original partialsFromDir.py script.

------------
Dependencies
------------

::

  Python: 2.2.[3-*]
  MineSight 3D: 4.0.*
  MineSight Grail: 4.0.*
  voxel.exe standalone engine and required dlls must be in path

-----
Usage
-----

This script runs interactively or silently. 

It can run from MineSight(R),from the command line, or executed by another script or program.

If run from MineSight(R), it is always interactive.

In interactive mode, a dialog is presented where your responses can be entered.
These responses can be saved to the .ini file and will be used to populate
the dialog thereafter. 

In silent mode, the dialog is not presented, and the script gets your
parameters from an ini file named *<script name>.ini*. Running in silent mode 
is useful for batch jobs or for including this script in procedures.

**To run interactively from command line:** 

::

  > createPartials.pyc


**To run silently from command line, send an argument of** *1* **:** 

::

  > createPartials.pyc 1 


**To run from MineSight(R):** 

::

  File-->Scripts-->Run Script...
  Browse for createPartials.pyc

-----------
Description
-----------

This script creates corresponding partials files for each shell element (surface or 
sold) residing in all of the geometry objects in a directory. The names of the
partials files can be user configured and an optional audit report of the run can be 
created. The partials files are generated by the voxel stand alone program.

This script runs interactively or silently (batch mode) from either 
MineSight(R) or the command line. See Usage_ for more information. 

When run interactively, the following panel is displayed:

.. figure:: startPanel.gif 

                  The Create Partials Dialog

After the RUN button is pressed, progress of the run is shown in the 
Progress window as the data is being processed. 
These details can be also written to the `Audit Report`_.

.. figure:: runningPanel.gif

                  Progress


When the processing is complete, another run, for example, using another
input directory, can be made by changing the values in the dialog and
pressing run again. 

.. figure:: donePanel.gif


                  Processing Complete 

Unexpected results and errors may occur due to the state of the original
shell the partials are generated from. For example, if the solid is not
closed or is outside of the project boundaries there may be an error in the
voxel engine or the resulting partials file may not be dependable.  

The partials files generated can be in integer or real format. See the
MineSight(R) Help for more information about partials files.

*Example Partials File*

::

	 62   0  65          70    41          46   62
	 62  43  66           0    67           1   62
	 62  43  68           1    69           0   62
	 -1   0   0           0     0           0   62
	 63   0  65          70    41          46   63
	 63  42  66           1    67           0   63
	 63  42  69           1    70           0   63
	 63  43  66           1    67           0   63
	 63  43  68           0    69           0   63
	 -1   0   0           0     0           0   63
	 64   0  65          70    41          46   64
	 64  41  65           0    66           0   64
	 64  41  67           0    68           0   64
	 64  41  69           0    70           0   64
	 64  42  65           0    66           1   64
	 64  42  69           1    70           0   64
	 64  43  65           0    66           0   64
	 64  43  70           0     0           0   64
	 64  44  65           0    66           0   64
	 64  44  70           0     0           0   64
	 64  45  65           0    66           0   64
	 64  45  70           0     0           0   64
	 64  46  65           0    66           0   64
	 64  46  67           0    68           0   64
	 64  46  69           0    70           0   64
	 -1   0   0           0     0           0   64

User instructions, or responses, are entered either in the graphical user
interface panel or specified in the response file. 


Responses
---------


**PCF (Project Control File)**

    Full path of the PCF file for the project. (xxx10.dat) 

    There is no default value for PCF, thus it is a required entry. 


**Input Directory**

    Full path to the directory of the geometry objects containing shell elements.

    Default Input Directory path is you current working directory or
    your project directory if running the script from MineSight(R)

**Output Directory**

    Full path to the directory where the partials files are written.

    Default Output Directory path is you current working directory or
    your project directory if running the script from MineSight(R)

**Sub Blocks**

    An integer in the range of 1 to 100.

    This is the subcell count voxel.exe uses to compute partials and the
    same value as the maximum of the X or Y default subcell count for
    volume calculations used in MineSight(R) File-->Project Settings-->Volumes.

.. figure:: projectSpaceSettings.gif

   MineSight(R) Project Space Settings


   Default sub blocks value is 10 in this script.

**Real**

    Boolean value indicating whether the values written in the partials
    files are in integer or float format. 

    - If set to one (1), or checked, partials files are written with float values.
    - If set to zero (0), or unchecked, partials files are written with integer values. 

    Default value for Real is zero or FALSE.

**Closed Solids Only**

    Boolean value indicating whether to use closed solids only.

    - If set to one (1), or checked, partials files are generated for closed solids only.
    - If set to zero (0), or unchecked, surfaces/solids with openings are skipped.

    Default value for using Closed Solids Only is zero or FALSE.

**Write Audit Report File**

    Boolean value indicating whether to create an audit report of the run.    

    - If set to one (1), or checked, a report is generated.
    - If set to zero (0), or unchecked, a report is not generated.

    Default value for Write Audit Report File is zero or FALSE.
 
**Spawn Report**

    Boolean value indicating whether to spawn the audit report in notepad.exe.    

    - If set to one (1), or checked, the report is spawned by notepad.exe.
    - If set to zero (0), or unchecked, a report is not spawned.

    If spawning the report, it will be spawned after the panel is closed in
    an interactive run, or after the processing is complete in a silent run. 

    Default value for Spawn Report is zero or FALSE.

**Report File Path**

    Full path for the report file. If the file already exists, it will be
    over-written. If the file does not exist, it will be created.

    Default value for Report File Path is createPartials.txt in your 
    current or project directory. 

**Partials File Names**

    String field indicating how to name the corresponding partials files
    created from each shell.

    Wildcards are available to build the partials file names:

        - $orig  = name of the original element, or attributed name
        - $obj   = name of the geometry object (.msr), or parent name
        - $count = incremental integer

    These wildcards can be combined to create unique names for all the 
    partials files created. Literals can also be combined with the wildcards.
    Example partials files names: 

        - high-$count.prt
        - low-$orig-$count.out 

.. warning:: 

          All partials' files names should be unique within each
          directory.  If file names are not unique, they will be
          overwritten.
 
          If creating partilas for subsequent processing, note that some
          programs may be restricted to reading ten character file
          names. 

          If using the wildcard $orig, be sure all shell elements are
          name attributed. 
..

    If $count wildcard is used, integer values for Start and Step are required.


    *Example File Naming using $obj-$count.prt*


	::

	      *Source*        *Partials File*
              pit3solid.msr -> pit3solid-1.prt
                            -> pit3solid-2.prt
                            -> pit3silid-n.prt
                            
                            where n is last solid in the .msr file and
                                  1 is first solid in the .msr file.
                        
              If a target file already exists, it will be overwritten. When there
              are multiple solids in one *.msr file, multiple *.prt files are created.

    Default value for Partials File Names is $obj-$count.prt: 
    which is the name of the geometry object (without .msr) a hyphen and
    sequential count, starting at one at each geometry object and 
    incremented by one for each shell element in that geometry object.
    The default extension of the partials files created is .prt.

**$count Start**

    Integer value indicating starting value for $count, which is a wildcard
    that can be used to build the output partials file names.

    Default $count Start value is one (1).


**$count Step**

    Integer value indicating the increment value for $count, which is a wildcard
    that can be used to build the output partials file names.

    Default $count Step value is one (1).

**$count Reset**

    Boolean value indicating whether to reset the wildcard $count start,
    which is a wildcard that can be used to build the output partials file names,
    at each new geometry object.     

    - If set to one (1), or checked, $count begins at $count start with each new
      geometry object encountered in the Input Directory.
    - If set to zero (0), or unchecked, $count is continuously incremented
      over all the geometry objects in the Input Directory.

    Default value for $count Reset is one or TRUE.


**Save Responses**

    Boolean value indicating whether to save the responses entered into
    the GUI panel to the .ini file. If running silently, the .ini file remains
    unchanged.    

    - If set to one (1), or checked, responses are saved to the .ini file.
    - If set to zero (0), or unchecked, responses are not saved to the .ini file.

    Responses are not saved unless an actual good run is made. If cancel is pressed
    before a successful run, the responses are not saved. 

    Default value for Save Responses is zero or FALSE.


Responses File Setup
--------------------

The best way to setup a response file is to run the script interactively
once and check Save Responses on the lower right corner of the dialog.
This will create a response file in the current working directory.

The name of the response file is always createPartials.ini.
If you rename the script, the subsequent response file created will be
script_name.ini.

The response file is simply a text file with tokens valued for each of the
parameters needed in the run. Comments can be entered in the .ini file with
a pound sign in column one. 

The format of the response file is: 

    token = value

    The token must be exactly as shown below in the example.
    The values should not be enclosed in quotes and should be 
    the type required, or an error will occur. 

**Example Response File** 

	::

	  PCF_FLN = C:\currentProject\rot10.dat
	  SOURCE_DIR = C:\currentProject\_msresources\high5
          # the following token, IO_IN_SAME_DIR is ignored in silent mode 
	  IO_IN_SAME_DIR =0
	  TARGET_DIR = C:\currentProject\_msresources\high5
	  SUB_BLOCKS = 10
	  REAL = 0
 	  PARTIALS_FLNS = $obj-$count.prt
	  COUNT_START = 1
	  COUNT_STEP = 1
	  COUNT_RESET = 1
	  CLOSED_SOLIDS_ONLY = 0
	  WRITE_RPT_FILE = 0
	  SPAWN_RPT_FILE = 0
	  RPT_FLN = C:\currentProject\createPartials.txt
          # the following token, SAVE_RESPONSES is ignored in silent mode 
	  SAVE_RESPONSES = 1


Audit Report
------------

If an audit of the run is desired, check the Write Audit Report File in the 
panel or set WRITE_RPT_FILE = 1 in the response file. Also, supply the 
report file path and indicate whether to spawn the report in notepad.exe. 

The report details the parameters sent to the voxel engine, information
about each shell element read and the partials file created from that element. 

**Example Audit Report** 

	::

	  ==================================================
	  D:\work\partials\createPartials.pyc
	  Tue Aug 21 15:45:06 2007
	  ==================================================
 	  PCF:              D:\currentProject\msop10.dat
	  Input Directory:  D:\CURRENTPROJECT\_MSRESOURCES\SHELLS
	  Output Directory: D:\CURRENTPROJECT\_MSRESOURCES\SHELLS
	  Voxel Parameters:
 	  -dx        20.0000 (Block width in x direction)
  	  -dy        20.0000 (Block width in y direction)
	  -dz        15.0000 (Block width in z direction)
 	  -nx       150      (Number of blocks in x direction)
 	  -ny       125      (Number of blocks in y direction)
 	  -nz        64      (Number of blocks in z direction)
 	  -xmin    1000.0000 (Min model limit in x direction)
 	  -ymin    4000.0000 (Min model limit in y direction)
	  -zmin    2000.0000 (Min model limit in z direction)
	  -sb        10      (Sub blocks)

	  --------------------------------------------------
	  Input geometry object:  Geometry1.msr
 	  --------------------------------------------------

	  Element 1: Skipped - Has openings.

	  Element 2: Skipped - Has openings.

	  Element 3: Output partials file:  cone-1.prt
	  Executing voxel ...
	  Reading data from disk ... done

	  Element 4: Output partials file:  cube-2.prt
	  Executing voxel ...
	  Reading data from disk ... done

	  Element 5: Output partials file:  cylinder-3.prt
	  Executing voxel ...
	  Reading data from disk ... done
          Error in voxel engine.

	  Element 6: Output partials file:  deciduous tree-4.prt
	  Executing voxel ...
	  Reading data from disk ... done

	  Element 7: Skipped - Has openings.

	  Element 8: Output partials file:  miner-5.prt
 	  Executing voxel ...
	  Reading data from disk ... done

	  Element 9: Skipped - Has openings.

	  Element 10: Output partials file:  sphere-6.prt
	  Executing voxel ...
	  Reading data from disk ... done

	  ==================================================
	  Total geometry objects processed: 1
	  Total elements processed: 6
	  ==================================================