Overview

This module contains various "transformation" routines for moving data from one file type to another.

Conversion Functions

msr2srv(msr_path, srv_path[, is_overwrite])

Converts all polylines, polygons, and markers in the Geometry MineSight(r) Resource (MSR) file found at msr_path to a SRV file at srv_path.

As a default the srv_path is always overwritten unless is_overwrite is set to False, in which case an IOError will be generated if the file exists.

srv2msr(srv_path, msr_path[, is_overwrite, name, material, options])

Converts a SRV file at srv_path to a Geometry MineSight(r) Resource (MSR) File at msr_path. It will return the Geometry object that was created to do this conversion. You can then use this object to do further processing.

As a default the msr_path is always overwritten unless is_overwrite is set to False, in which case an IOError will be generated if the file exists. The name, material and options will be applied to the new elements within the Geometry object created at the given msr_path.

A basic example:

msr2srg(msr_path, srg_path[, is_overwrite])

Converts all polylines, polygons, and markers in the Geometry MineSight(r) Resource (MSR) file found at msr_path to a SRG file at srg_path.

As a default the srg_path is always overwritten unless is_overwrite is set to False, in which case an IOError will be generated if the file exists.

srg2msr(srg_path, msr_path[, is_overwrite, name, material, options])

Converts a SRG file at srg_path to a Geometry MineSight(r) Resource (MSR) File at msr_path. It will return the Geometry object that was created to do this conversion. You can then use this object to do further processing.

As a default the msr_path is always overwritten unless is_overwrite is set to False, in which case an IOError will be generated if the file exists.

A basic example:

msr2shl(msr_path, shl_path[, name_matches, is_overwrite])

Converts a shell in the Geometry MineSight(r) Resource (MSR) file found at msr_path to a SHL file at shl_path. By default it will convert the first shell found within the MSR file. This function will return a tuple of name, material and option for the Shell found where given name_matches the name of the Shell within the MSR file. The match is performed using the Python fnmatch [1] library. By default, the name_matches is set to "*" and will match the first shell within the MSR.

If the msr_path does not contain a Shell, this function will generate an IOError.

As a default the shl_path is always overwritten unless is_overwrite is set to False, in which case an IOError will be generated.

A simple example of using this function is as follows,

        # Will overwrite the contents of `shl_path` with the first Shell found
        # in the MSR file at `msr_path`.
        transform.msr2shl(msr_path, shl_path)

If you do not want to overwrite an existing file, you can set is_overwrite to true, and ensure that an IOError is generated when a file exists at shl_path.

        try:
            geom_msr = transform.msr2shl(
                msr_path, shl_path, is_overwrite=False
                )
        except IOError, why:
            # An exception would be thrown if `msr_path` existed since we made
            # sure that we didn't overwrite any existing file.
            print str(why)

In this case an error string will be printed if the shl_path already exists.

The following example shows how you can keep information about the Shell in the MSR file.

        name, material, options = transform.msr2shl(msr_path, shl_path)

where the name, material, and options are all from the MSR via the getshellnameat, getshellmaterialat, and 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.

        name, material, option = transform.msr2shl(
            msr_path,
            shl_path,
            name_matches="gold"
            )

where the Shell stored at the shl_path will be the first Shell in the MSR that has the name gold.

shl2msr(shl_path, msr_path[, origin, is_overwrite, name, material, options])

Converts a SHL file at shl_path to a Geometry MineSight(r) Resource (MSR) File at msr_path. It will return the Geometry object that was created to do this conversion. You can then use this object to do further processing.

As a default the msr_path is always overwritten unless is_overwrite is set to False, in which case an IOError will be generated. The name, material and options will be applied to the new Shell within the Geometry object created at the given msr_path.

A basic example would be,

        # Convert it from shl_path to the msr_path, should return
        # a handle to a grail.data.geometry.Geometry object. Make
        # a backup of the original (if it exists).
        transform.backup_safe(msr_path)
        geom_msr = transform.shl2msr(shl_path, msr_path)

if the msr_path existed, then this would overwrite the existing file with the contents of shl_path. However, by using the backup_safe call, we ensured that if there was a msr_path, we made a backup of that file in the same directory.

The geom_msr returned is a Geometry object that you can edit to your hearts content.

The following example illustrates calling this function with is_overwrite equal to false.

        try:
            geom_msr = transform.shl2msr(
                shl_path, msr_path, is_overwrite=False
                )
        except IOError, why:
            # An exception would be thrown if `msr_path` existed since we made
            # sure that we didn't overwrite any existing file.
            print "error", str(why)

In most cases you will want to specify an origin for your shell data so you don't loose precision when you add it to your MSR file. As a default an origin of [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 origin,

        # In this case we are going to compute the "best" origin for the
        # data set. This may be slow, but accurate; in other cases you may
        # use the project settings to compute the origin.
        optimal_origin = ag.pointlistcenter(shl_points)
        geom_msr = transform.shl2msr(shl_path, msr_path, origin=optimal_origin)

In this case the geom_msr will have an origin at optimal_origin.

See also grail.data.shlfile and grail.data.geometry.

Utility Functions

The following functions are generally helpful when working with file conversions.

backup(path [,backup_char, delete_original])

Creates a backup of the file at path, and returns a new path for that file.

The backup is created by taking the existing path and appending the backup_char to it. By default the backup_char is "%". As an example, the c:\project\somefile.msr would become c:\project\somefile.msr%.

An example would be,

        # Make a backup, perserve the orginal.
        backup_path = transform.backup(data_path)

if you wanted to delete the original you would do something like,

        # Make a backup, perserve the orginal.
        backup_path = transform.backup(
            data_path, delete_original=True
            )

If delete_original is set to True the file at path will be removed. By default delete_original is set to False.

If there is no file at the given path, this function will generate an IOError. Consider using the backup_safe function instead.

backup_safe(path [,backup_char, delete_original])

The backup_safe function will attempt to make a backup of the file at the given path; however, if there is no file at 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