=============================== ``grail.data.transform`` Module =============================== .. include:: ..\version.h .. contents:: Table of Contents :backlinks: top -------- Overview -------- This module contains various "transformation" routines for moving data from one file type to another. -------------------- Conversion Functions -------------------- :df:`msr2srv(msr_path, srv_path[, is_overwrite])` Converts all polylines, polygons, and markers in the Geometry MineSight(r) Resource (MSR) file found at :a:`msr_path` to a SRV file at :a:`srv_path`. As a default the :a:`srv_path` is always overwritten unless :a:`is_overwrite` is set to :d:`False`, in which case an :e:`IOError` will be generated if the file exists. :df:`srv2msr(srv_path, msr_path[, is_overwrite, name, material, options])` Converts a SRV file at :a:`srv_path` to a Geometry MineSight(r) Resource (MSR) File at :a:`msr_path`. It will return the :c:`Geometry` object that was created to do this conversion. You can then use this object to do further processing. As a default the :a:`msr_path` is always overwritten unless :a:`is_overwrite` is set to :d:`False`, in which case an :e:`IOError` will be generated if the file exists. The :a:`name`, :a:`material` and :a:`options` will be applied to the new elements within the :c:`Geometry` object created at the given :a:`msr_path`. A basic example: .. Python:: geom_msr = transform.srv2msr(srv_path, msr_path, is_overwrite=False, name="blast pattern", material="blasthole", options=None) :df:`msr2srg(msr_path, srg_path[, is_overwrite])` Converts all polylines, polygons, and markers in the Geometry MineSight(r) Resource (MSR) file found at :a:`msr_path` to a SRG file at :a:`srg_path`. As a default the :a:`srg_path` is always overwritten unless :a:`is_overwrite` is set to :d:`False`, in which case an :e:`IOError` will be generated if the file exists. :df:`srg2msr(srg_path, msr_path[, is_overwrite, name, material, options])` Converts a SRG file at :a:`srg_path` to a Geometry MineSight(r) Resource (MSR) File at :a:`msr_path`. It will return the :c:`Geometry` object that was created to do this conversion. You can then use this object to do further processing. As a default the :a:`msr_path` is always overwritten unless :a:`is_overwrite` is set to :d:`False`, in which case an :e:`IOError` will be generated if the file exists. A basic example: .. Python:: geom_msr = transform.srg2msr(srg_path, msr_path, is_overwrite=False, name="blast pattern", material="blasthole", options=None) :df:`msr2shl(msr_path, shl_path[, name_matches, is_overwrite])` Converts a shell in the Geometry MineSight(r) Resource (MSR) file found at :a:`msr_path` to a SHL file at :a:`shl_path`. By default it will convert the first shell found within the MSR file. This function will return a tuple of :a:`name`, :a:`material` and :a:`option` for the Shell found where given :a:`name_matches` the name of the Shell within the MSR file. The match is performed using the Python `fnmatch` [#python-lib-fnmatch]_ library. By default, the :a:`name_matches` is set to "*" and will match the first shell within the MSR. If the :a:`msr_path` does not contain a Shell, this function will generate an :e:`IOError`. As a default the :a:`shl_path` is always overwritten unless :a:`is_overwrite` is set to :d:`False`, in which case an :e:`IOError` will be generated. A simple example of using this function is as follows, .. code-block-incl:: Python :file: ..\..\..\grail\test\transformtest.py :start: start_basic_msr2shl_ex :end: end_basic_msr2shl_ex If you do not want to overwrite an existing file, you can set :a:`is_overwrite` to true, and ensure that an :e:`IOError` is generated when a file exists at :a:`shl_path`. .. code-block-incl:: Python :file: ..\..\..\grail\test\transformtest.py :start: start_msr2shl_overwrite_false_ex :end: end_msr2shl_overwrite_false_ex In this case an error string will be printed if the :d:`shl_path` already exists. The following example shows how you can keep information about the Shell in the MSR file. .. code-block-incl:: Python :file: ..\..\..\grail\test\transformtest.py :start: start_msr2shl_return_ex :end: end_msr2shl_return_ex where the :d:`name`, :d:`material`, and :d:`options` are all from the MSR via the :f:`getshellnameat`, :f:`getshellmaterialat`, and :f:`getshelloptionsat` functions. Finally, the following example illustrates how you can "find" a shell within the MSR, and only generate a SHL file where the name has the first match. .. code-block-incl:: Python :file: ..\..\..\grail\test\transformtest.py :start: start_using_name_matches_ex :end: end_using_name_matches_ex where the Shell stored at the :d:`shl_path` will be the first Shell in the MSR that has the name :d:`gold`. :df:`shl2msr(shl_path, msr_path[, origin, is_overwrite, name, material, options])` Converts a SHL file at :a:`shl_path` to a Geometry MineSight(r) Resource (MSR) File at :a:`msr_path`. It will return the :c:`Geometry` object that was created to do this conversion. You can then use this object to do further processing. As a default the :a:`msr_path` is always overwritten unless :a:`is_overwrite` is set to :d:`False`, in which case an :e:`IOError` will be generated. The :a:`name`, :a:`material` and :a:`options` will be applied to the new Shell within the :c:`Geometry` object created at the given :a:`msr_path`. A basic example would be, .. code-block-incl:: Python :file: ..\..\..\grail\test\transformtest.py :start: start_basic_shl2msr_ex :end: end_basic_shl2msr_ex if the :d:`msr_path` existed, then this would **overwrite** the existing file with the contents of :d:`shl_path`. However, by using the :f:`backup_safe` call, we ensured that if there was a :d:`msr_path`, we made a backup of that file in the same directory. The :d:`geom_msr` returned is a :c:`Geometry` object that you can edit to your hearts content. The following example illustrates calling this function with :a:`is_overwrite` equal to false. .. code-block-incl:: Python :file: ..\..\..\grail\test\transformtest.py :start: start_msr_overwrite_false_ex :end: end_msr_overwrite_false_ex In most cases you will want to specify an :a:`origin` for your shell data so you don't loose precision when you add it to your MSR file. As a default an :a:`origin` of :d:`[0., 0., 0.]` is used. In the example below, we compute the center of the shell data (slow), in most cases you would use the project settings (faster) to figure out a good :a:`origin`, .. code-block-incl:: Python :file: ..\..\..\grail\test\transformtest.py :start: start_shl2msr_with_origin_ex :end: end_shl2msr_with_origin_ex In this case the :d:`geom_msr` will have an origin at :a:`optimal_origin`. See also grail.data.shlfile_ and grail.data.geometry_. .. _grail.data.shlfile: shlfile.html .. _grail.data.geometry: lib-grail-data-geometry.html ----------------- Utility Functions ----------------- The following functions are generally helpful when working with file conversions. :df:`backup(path [,backup_char, delete_original])` Creates a backup of the file at :a:`path`, and returns a new path for that file. The backup is created by taking the existing path and appending the :a:`backup_char` to it. By default the :a:`backup_char` is "%". As an example, the :file:`c:\\project\\somefile.msr` would become :file:`c:\\project\\somefile.msr%`. An example would be, .. code-block-incl:: Python :file: ..\..\..\grail\test\transformtest.py :start: start_basic_backup_ex :end: end_basic_backup_ex if you wanted to delete the original you would do something like, .. code-block-incl:: Python :file: ..\..\..\grail\test\transformtest.py :start: start_backup_delete_original_ex :end: end_backup_delete_original_ex If :a:`delete_original` is set to :d:`True` the file at :a:`path` will be removed. By default :a:`delete_original` is set to :d:`False`. If there is no file at the given :a:`path`, this function will generate an :e:`IOError`. Consider using the :f:`backup_safe` function instead. :df:`backup_safe(path [,backup_char, delete_original])` The :f:`backup_safe` function will attempt to make a :f:`backup` of the file at the given :a:`path`; however, if there is no file at :a:`path`, then this function does nothing and returns a blank string. It is useful for the cases where you want to make a backup before a transformation, but don't really care if the target file exists or not. ---------- References ---------- .. [#python-lib-fnmatch] "fnmatch -- Unix filename pattern matching" *Python Library Reference* 21 Feburary 2008. 26 May 2008.