=============================
``grail.data.dxffile`` Module
=============================
.. include:: ..\..\version.h

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


--------
Overview
--------

The Drawing eXchange Format (DXF) is one of the most widely supported vector formats
in Computer-Aided Design.  It was developed with the purpose of enabling data 
interoperability between different CAD systems. The format is supported by many 
programs including MineSight, AutoCAD, Visio, and ArcMap.

DXF files can be used for storing many types of geometries. This module supports 
the reading and writing of labels, polylines, markers, and shells (solids/surfaces).


--------
Examples
--------

The following snippet illustrates how to read from a DXF file,

.. Python::

  	# Open a "sample_path" and read the points and face data from the first shell
	dxf = dxffile.open(sample_path, 'r')

	if dxf.getshellcount() > 0:
            point_list = dxf.getshellpointsat(0)
            face_list = dxf.getshellfacesat(0)

        dxf.close()   


At this point the :d:`point_list` and :d:`face_list` contain the
standard point and face lists as defined in the grail.ag_ module's
`Standard Definitions`_.

.. _grail.ag: ../lib-grail-ag.html
.. _Standard Definitions: ../lib-grail-ag.html#standard-definitions

An example of writing geometry data to DXF is as follows,

.. Python::

	# Open a "sample_path" and write out a polyline and point.
	dxf = dxffile.open(sample_path, 'w')

	pList = [[0,0,0],[1,1,1],[2,2,2]]
	dxf.addpolyline(pList, "contour")

	#note that even though we only have one point, we must pass it in as a list
	point = [0.0, 0.0, 0.0]
	dxf.addmarkers([point], "layer6")

	dxf.close()


--------
Function
--------

:df:`open(path [,mode])`

   Opens a file at the given :a:`path`. The :a:`mode` can be either "r"
   for read-only, or "w" for write-only. If you want to create a new file 
   use the "w" option (if the file exists, it will be overwritten). Mode 
   is read-only by default.

   If you are attempting to open a file in "r" mode and it does not
   exist, an :e:`IOError` is generated.

-------
DXF
-------

:c:`DXF`

   Use the :df:`open` function to load/create a :c:`DXF` object. For
   the most part this object behaves as a regular file object in
   Python.

   **Methods**

      :df:`addlabel(position, text, size, layername)`
         Append a new label element to the file.

      :df:`addmarkers(point, layername)`
         Append a new markers element to the file.

      :df:`addpolyline(point_list, layername)`
         Append a new polyline to the file.

      :df:`addshell(point_list, face_list, layername)`
         Append a new shell to the file.

      :df:`getlabelcount()`
         Return the number of labels in the file.

      :df:`getlabelpositionat(idx)`
         Return the label's position at the given index.

      :df:`getlabeltextat(idx)`
         Return the label's text value at the given index.

      :df:`getlabelsizeat(idx)`
         Return the label's size at the given index.

      :df:`getmarkerspointsat(idx)`
         Return the markers points at the given index.

      :df:`getmarkerscount()`
         Return the number of markers in the file.

      :df:`getmarkerspointsat(idx)`
         Return the markers points at the given index.

      :df:`getpolylinecount()`
         Return the number of polylines in the file.

      :df:`getpolylinepointsat(idx)`
         Return the polyline points at the given index.

      :df:`getshellcount()`
         Return the number of shells in the file.

      :df:`getshellpointsat(idx)`
         Return the shell points at the given index.

      :df:`getshellfacesat(idx)`
         Return the shell faces at the given index.

      :df:`close()`
         This closes the file handle to the object. If you fail to close
         the file explicitly, the file will be closed implicitly when
         object falls out of scope.

   **Attributes**

      :dd:`mode`

         Indicates the mode that the file is in. For example
         this would be "r" (read-only), or "w" (write-only).

      :dd:`name`

         This is the path to the file.

      :dd:`closed`
 
         Is :d:`True` when the object has been closed.