19. geomfile — Export/import of files in pyFormex’s native PGF format

This module defines a class to work with files in the native pyFormex Geometry File (PGF) format.

class geomfile.GeometryFile(filename, mode=None, compr=None, level=5, delete_temp=True, sep=' ', ifmt=None, ffmt=None, version=None)

A class to handle files in the pyFormex Geometry File format.

The pyFormex Geometry File (PGF) format allows the persistent storage of most of the geometrical objects available in pyFormex using a format that is independent of the pyFormex version. It guarantees a possible read back in future versions. The format is simple and public, and hence also allows read back from other software.

See http://pyformex.org/doc/file_format for a full description of the file format(s). Older file formats are supported for reading.

Other than just geometry, the pyFormex Geometry File format can also store some attributes of the objects, like names and colors. Future versions will also allow to store field variables.

The GeometryFile class uses the utils.File class to access the files, and thus provides for transparent compression and decompression of the files. When making use of the compression, the PGF files will remain small even for complex models.

A PGF file starts with a specific header identifying the format and version. When opening a file for reading, the PGF header is read automatically, and the file is thus positioned ready for reading the objects. When opening a file for writing (not appending!), the header is automatically written, and the file is ready for writing objects.

In append mode however, nothing is currently done with the header. This means that it is possible to append to a file using a format different from that used to create the file initially. This is not a good practice, as it may hinder the proper read back of the data. Therefore, append mode should only be used when you are sure that your current pyFormex uses the same format as the already stored file. As a reminder, warning is written when opening the file in append mode.

The filename, mode, compr, level and delete_temp arguments are passed to the utils.File class. See utils.File for more details.

Parameters:

• filename (path_like) – The name of the file to open. If the file name ends with ‘.gz’ or ‘.bz2’, transparent (de)compression will be used, as provided by the utils.File class.
• mode ('rb', 'wb' or 'ab') – Specifies that the file should be opened in read, write or append mode respectively. If omitted, an existing file will be opened in read mode and a non-existing in write mode. Opening an existing file in ‘wb’ mode will overwrite the file, while opening it in ‘ab’ mode will allow to append to the file.
• compr ('gz' or 'bz2') – The compression type to be used: gzip or bzip2. If the file name is ending with ‘.gz’ or ‘.bz2’, this is set automatically from the suffix.
• level (int 1..9) – Compression level for gzip/bzip2. Higher values result in smaller files, but require longer compression times. The default of 5 gives already a fairly good compression ratio.
• delete_temp (bool) – If True (default), the temporary files needed to do the (de)compression are deleted when the GeometryFile is closed.
• sep (str) – Separator string to be used when writing numpy arrays to the file. An empty string will make the arrays being written in binary format. Any other string will force text mode, and the sep string is used as a separator between subsequent array elements. See also numpy.tofile().
• ifmt (str) – Format for integer items when writing in text mode.
• ffmt (str) – Format for float items when writing in test mode.
• version (str) – Version of PGF format to use when writing. Currently available are ‘1.9’, ‘2.0’, ‘2.1’. The default is ‘2.1’.

readline()

Read a line from the file

writeline(s)

Write a text line to the file

reopen(mode='rb')

Reopen the file, possibly changing the mode.

The default mode for the reopen is ‘rb’

close()

Close the file.

writeHeader()

Write the header of a pyFormex geometry file.

The header identifies the file as a pyFormex geometry file and sets the following global values:

• version: the version of the geometry file format
• sep: the default separator to be used when not specified in the data block

writeData(data, sep)

Write an array of data to a pyFormex geometry file.

If fmt is None, the data are written using numpy.tofile, with the specified separator. If sep is an empty string, the data block is written in binary mode, leading to smaller files. If fmt is specified, each

write(geom, name=None, sep=None)

Write a collection of Geometry objects to the Geometry File.

Parameters:geom (object) – An object of one the supported Geometry data types or a list or dict of such objects, or a WebGL objdict. Currently exported geometry objects are Coords, Formex, Mesh, PolyLine, BezierSpline. Returns:int – The number of objects written.

writeGeometry(geom, name=None, sep=None)

Write a single Geometry object.

Writes a single Geometry object to the Geometry File, using the specified name and separator.

Parameters:

• geom (a supported Geometry type object) – Currently supported Geometry objects are Coords, Formex, Mesh, TriSurface, PolyLine, BezierSpline. Other types are skipped, and a message is written, but processing continues.
• name (str, optional) – The name of the object to be stored in the file. If not specified, and the object has an attrib dict containing a name, that value is used. Else an object name is generated from the file name. On readback, the object names are used as keys to store the objects in a dict.
• sep (str) – The separator to be used for writing this object. If not specified, the value given in the constructor will be used. This argument allows to override it on a per object base.
• 1 if the object has been written, 0 otherwise. (Returns) –

writeFMT(F, name=None, sep=None)

Write a Formex, Mesh or TriSurface.

Parameters:

• F (Formex, Mesh or TriSurface) – The object to be written.
• name (str) – See writeGeometry()
• sep (str) – See writeGeometry()

Notes

This writes a header line with these attributes and arguments: objtype, ncoords, nelems, nplex, props(True/False), eltype, normals(True/False), color, sep, name. This is followed by the array data for: coords, elems, prop, normals, color

The objtype can/should be overridden for subclasses.

writeCurve(F, name=None, sep=None, objtype=None, extra=None)

Write a Curve to a pyFormex geometry file.

This function writes any curve type to the geometry file. The objtype is automatically detected but can be overridden.

The following attributes and arguments are written in the header: ncoords, closed, name, sep. The following attributes are written as arrays: coords

writePolyLine(F, name=None, sep=None)

Write a PolyLine to a pyFormex geometry file.

This is equivalent to writeCurve(F,name,sep,objtype=’PolyLine’)

writeBezierSpline(F, name=None, sep=None)

Write a BezierSpline to a pyFormex geometry file.

This is equivalent to writeCurve(F,name,sep,objtype=’BezierSpline’)

writeNurbsCurve(F, name=None, sep=None, extra=None)

Write a NurbsCurve to a pyFormex geometry file.

This function writes a NurbsCurve instance to the geometry file.

The following attributes and arguments are written in the header: ncoords, nknots, closed, name, sep. The following attributes are written as arrays: coords, knots

writeNurbsSurface(F, name=None, sep=None, extra=None)

Write a NurbsSurface to a pyFormex geometry file.

This function writes a NurbsSurface instance to the geometry file.

The following attributes and arguments are written in the header: ncoords, nknotsu, nknotsv, closedu, closedv, name, sep. The following attributes are written as arrays: coords, knotsu, knotsv

writeAttrib(attrib)

Write the Attributes block of the Geometry

Parameters:attrib (Attributes) – The Attributes dict of a Geometry object.

Warning

This is work in progress. Not all Attributes can currently be stored in the PGF format.

read(count=-1, warn_version=True)

Read objects from a pyFormex Geometry File.

This function reads objects from a Geometry File until the file ends, or until count objects have been read. The File should have been opened for reading.

A count may be specified to limit the number of objects read.

Returns a dict with the objects read. The keys of the dict are the object names found in the file. If the file does not contain object names, they will be autogenerated from the file name.

Note that PGF files of version 1.0 are no longer supported. The use of formats 1.1 to 1.5 is deprecated, and users are urged to upgrade these files to a newer format. Support for these formats may be removed in future.

decode(s)

Decode the announcement line.

Returns a dict with the interpreted values of the line.

readHeader(s=None)

Read the header of a pyFormex geometry file.

Without argument, reads a line from the file and interpretes it as a header line. This is normally used to read the first line of the file. A string s may be specified to interprete further lines as a header line.

doHeader(version='1.1', sep='', **kargs)

Read the header of a pyFormex geometry file.

Sets detected default values

readGeometry(objtype='Formex', name=None, nelems=None, ncoords=None, nplex=None, props=None, eltype=None, normals=None, color=None, colormap=None, closed=None, degree=None, nknots=None, sep=None, **kargs)

Read a geometry record of a pyFormex geometry file.

If an object was successfully read, it is set in self.geometry

readField(field=None, fldtype=None, shape=None, sep=None, **kargs)

Read a Field defined on the last read geometry.

readAttrib(attrib=None, **kargs)

Read an Attributes dict defined on the last read geometry.

readFormex(nelems, nplex, props, eltype, sep)

Read a Formex from a pyFormex geometry file.

The coordinate array for nelems*nplex points is read from the file. If present, the property numbers for nelems elements are read. From the coords and props a Formex is created and returned.

readMesh(ncoords, nelems, nplex, props, eltype, normals, sep, objtype='Mesh')

Read a Mesh from a pyFormex geometry file.

The following arrays are read from the file: - a coordinate array with ncoords points, - a connectivity array with nelems elements of plexitude nplex, - if present, a property number array for nelems elements.

Returns the Mesh constructed from these data, or a subclass if an objtype is specified.

readPolyLine(ncoords, closed, sep)

Read a Curve from a pyFormex geometry file.

The coordinate array for ncoords points is read from the file and a Curve of type objtype is returned.

readBezierSpline(ncoords, closed, degree, sep)

Read a BezierSpline from a pyFormex geometry file.

The coordinate array for ncoords points is read from the file and a BezierSpline of the given degree is returned.

readNurbsCurve(ncoords, nknots, closed, sep)

Read a NurbsCurve from a pyFormex geometry file.

The coordinate array for ncoords control points and the nknots knot values are read from the file. A NurbsCurve of degree p = nknots - ncoords - 1 is returned.

readNurbsSurface(ncoords, nuknots, nvknots, uclosed, vclosed, sep)

Read a NurbsSurface from a pyFormex geometry file.

The coordinate array for ncoords control points and the nuknots and nvknots values of uknots and vknots are read from the file. A NurbsSurface of degree pu = nuknots - ncoords - 1 and pv = nvknots - ncoords - 1 is returned.

readLegacy(count=-1)

Read the objects from a pyFormex Geometry File format <= 1.7.

This function reads all the objects of a Geometry File. The File should have been opened for reading, and the header should have been read previously.

A count may be specified to limit the number of objects read.

Returns a dict with the objects read. The keys of the dict are the object names found in the file. If the file does not contain object names, they will be autogenerated from the file name.

oldReadBezierSpline(ncoords, nparts, closed, sep)

Read a BezierSpline from a pyFormex geometry file version 1.3.

The coordinate array for ncoords points and control point array for (nparts,2) control points are read from the file. A BezierSpline is constructed and returned.

rewrite()

Convert the geometry file to the latest format.

The conversion is done by reading all objects from the geometry file and writing them back. Parts that could not be successfully read will be skipped.