1.. _arch-usr: 2 3Usage for Beginners 4=================== 5 6This section shows the intended usage of the `ezdxf` package. 7This is just a brief overview for new `ezdxf` users, follow the provided links 8for more detailed information. 9 10 11First import the package:: 12 13 import ezdxf 14 15Loading DXF Files 16----------------- 17 18`ezdxf` supports loading ASCII and binary DXF files from a file:: 19 20 doc = ezdxf.readfile(filename) 21 22or from a zip-file:: 23 24 doc = ezdxf.readzip(zipfilename[, filename]) 25 26Which loads the DXF file `filename` from the zip-file `zipfilename` or the 27first DXF file in the zip-file if `filename` is absent. 28 29It is also possible to read a DXF file from a stream by the :func:`ezdxf.read` 30function, but this is a more advanced feature, because this requires detection 31of the file encoding in advance. 32 33This works well with DXF files from trusted sources like AutoCAD or BricsCAD, 34for loading DXF files with minor or major flaws look at the 35:mod:`ezdxf.recover` module. 36 37.. seealso:: 38 39 Documentation for :func:`ezdxf.readfile`, :func:`ezdxf.readzip` and 40 :func:`ezdxf.read`, for more information about file 41 management go to the :ref:`dwgmanagement` section. For loading DXF files 42 with structural errors look at the :mod:`ezdxf.recover` module. 43 44Saving DXF Files 45---------------- 46 47Save the DXF document with a new name:: 48 49 doc.saveas('new_name.dxf') 50 51or with the same name as loaded:: 52 53 doc.save() 54 55.. seealso:: 56 57 Documentation for :func:`ezdxf.document.Drawing.save` and 58 :func:`ezdxf.document.Drawing.saveas`, for more information about file 59 management go to the :ref:`dwgmanagement` section. 60 61Create a New DXF File 62--------------------- 63 64Create new file for the latest supported DXF version:: 65 66 doc = ezdxf.new() 67 68Create a new DXF file for a specific DXF version, e.g for DXF R12:: 69 70 doc = ezdxf.new('R12') 71 72 73To setup some basic DXF resources use the `setup` argument:: 74 75 doc = ezdxf.new(setup=True) 76 77.. seealso:: 78 79 Documentation for :func:`ezdxf.new`, for more information about file 80 management go to the :ref:`dwgmanagement` section. 81 82Layouts and Blocks 83------------------ 84 85Layouts are containers for DXF entities like LINE or CIRCLE. The most important 86layout is the modelspace labeled as "Model" in CAD applications which represents 87the "world" work space. Paperspace layouts represents plottable sheets which 88contains often the framing and the tile block of a drawing and VIEWPORT entities 89as scaled and clipped "windows" into the modelspace. 90 91The modelspace is always present and can not be deleted. The active paperspace 92is also always present in a new DXF document but can be deleted, in that case 93another paperspace layout gets the new active paperspace, but you can not delete 94the last paperspace layout. 95 96Getting the modelspace of a DXF document:: 97 98 msp = doc.modelspace() 99 100Getting a paperspace layout by the name as shown in the tab of a 101CAD application:: 102 103 psp = doc.layout('Layout1') 104 105A block is just another kind of entity space, which can be inserted 106multiple times into other layouts and blocks by the INSERT entity also called 107block references, this is a very powerful and important concept of the DXF 108format. 109 110Getting a block layout by the block name:: 111 112 blk = doc.blocks.get('NAME') 113 114 115All these layouts have factory functions to create graphical DXF entities for 116their entity space, for more information about creating entities see section: 117`Create new DXF Entities`_ 118 119Create New Blocks 120----------------- 121 122The block definitions of a DXF document are managed by the 123:class:`~ezdxf.sections.blocks.BlocksSection` object:: 124 125 my_block = doc.blocks.new('MyBlock') 126 127.. seealso:: 128 129 :ref:`tut_blocks` 130 131Query DXF Entities 132------------------ 133 134As said in the `Layouts and Blocks`_ section, all graphical DXF entities are 135stored in layouts, all these layouts can be iterated and support the index 136operator e.g. :code:`layout[-1]` returns the last entity. 137 138The main difference between iteration and index access is, that iteration filters 139destroyed entities, but the the index operator returns also destroyed entities 140until these entities are purged by :code:`layout.purge()` more about this topic 141in section: `Delete Entities`_. 142 143There are two advanced query methods: :meth:`~ezdxf.layouts.BaseLayout.query` 144and :meth:`~ezdxf.layouts.BaseLayout.groupby`. 145 146Get all lines of layer ``'MyLayer'``:: 147 148 lines = msp.query('LINE[layer=="MyLayer"]') 149 150This returns an :class:`~ezdxf.query.EntityQuery` container, which also provides 151the same :meth:`query` and :meth:`groupby` methods. 152 153Get all lines categorized by a DXF attribute like color:: 154 155 all_lines_by_color = msp.query('LINE').groupby('color') 156 lines_with_color_1 = all_lines_by_color.get(1, []) 157 158The :meth:`groupby` method returns a regular Python :class:`dict` with colors as 159key and a regular Python :class:`list` of entities as values 160(not an :class:`~ezdxf.query.EntityQuery` container). 161 162.. seealso:: 163 164 For more information go to the :ref:`tut_getting_data` 165 166Examine DXF Entities 167-------------------- 168 169Each DXF entity has a :attr:`dxf` namespace attribute, which stores the named 170DXF attributes, some DXF attributes are only indirect available like the 171vertices in the LWPOLYLINE entity. More information about the DXF attributes of 172each entity can found in the documentation of the :mod:`ezdxf.entities` module. 173 174Get some basic DXF attributes:: 175 176 layer = entity.dxf.layer # default is '0' 177 color = entity.dxf.color # default is 256 = BYLAYER 178 179Most DXF attributes have a default value, which will be returned if the DXF 180attribute is not present, for DXF attributes without a default value you can 181check in the attribute really exist:: 182 183 entity.dxf.hasattr('true_color') 184 185or use the :meth:`get` method and a default value:: 186 187 entity.dxf.get('true_color', 0) 188 189.. seealso:: 190 191 :ref:`Common graphical DXF attributes` 192 193Create New DXF Entities 194----------------------- 195 196The factory functions for creating new graphical DXF entities are located in the 197:class:`~ezdxf.layouts.BaseLayout` class. This means this factory function are 198available for all entity containers: 199 200 - :class:`~ezdxf.layouts.Modelspace` 201 - :class:`~ezdxf.layouts.Paperspace` 202 - :class:`~ezdxf.layouts.BlockLayout` 203 204The usage is simple:: 205 206 msp = doc.modelspace() 207 msp.add_line((0, 0), (1, 0), dxfattribs={'layer': 'MyLayer'}) 208 209A few important or required DXF attributes are explicit method arguments, 210most additional and optional DXF attributes are gives as a regular Python 211:class:`dict` object. 212The supported DXF attributes can be found in the documentation of the 213:mod:`ezdxf.entities` module. 214 215.. warning:: 216 217 Do not instantiate DXF entities by yourself and add them to layouts, always 218 use the provided factory function to create new graphical entities, this is 219 the intended way to use `ezdxf`. 220 221Create Block References 222----------------------- 223 224A block reference is just another DXF entity called INSERT, but the term 225"Block Reference" is a better choice and so the :class:`~ezdxf.entities.Insert` 226entity is created by the factory function: 227:meth:`~ezdxf.layouts.BaseLayout.add_blockref`:: 228 229 msp.add_blockref('MyBlock') 230 231 232.. seealso:: 233 234 See :ref:`tut_blocks` for more advanced features like using 235 :class:`~ezdxf.entities.Attrib` entities. 236 237 238Create New Layers 239----------------- 240 241A layer is not an entity container, a layer is just another DXF attribute 242stored in the entity and this entity can inherit some properties from this 243:class:`~ezdxf.entities.Layer` object. 244Layer objects are stored in the layer table which is available as 245attribute :code:`doc.layers`. 246 247You can create your own layers:: 248 249 my_layer = doc.layer.new('MyLayer') 250 251The layer object also controls the visibility of entities which references this 252layer, the on/off state of the layer is unfortunately stored as positive or 253negative color value which make the raw DXF attribute of layers useless, to 254change the color of a layer use the property :attr:`Layer.color` :: 255 256 my_layer.color = 1 257 258To change the state of a layer use the provided methods of the 259:class:`~ezdxf.entities.Layer` object, like 260:meth:`~ezdxf.entities.Layer.on`, :meth:`~ezdxf.entities.Layer.off`, 261:meth:`~ezdxf.entities.Layer.freeze` or :meth:`~ezdxf.entities.Layer.thaw`:: 262 263 my_layer.off() 264 265.. seealso:: 266 267 :ref:`layer_concept` 268 269Delete Entities 270--------------- 271 272The safest way to delete entities is to delete the entity from the layout 273containing that entity:: 274 275 line = msp.add_line((0, 0), (1, 0)) 276 msp.delete_entity(line) 277 278This removes the entity immediately from the layout and destroys the entity. 279The property :attr:`~ezdxf.entities.DXFEntity.is_alive` returns ``False`` for a 280destroyed entity and all Python attributes are deleted, so 281:code:`line.dxf.color` will raise an :class:`AttributeError` exception, 282because ``line`` does not have a :attr:`~ezdxf.entities.DXFEntity.dxf` 283attribute anymore. 284 285The current version of `ezdxf` also supports also destruction of entities 286by calling method :meth:`~ezdxf.entities.DXFEntity.destroy` manually:: 287 288 line.destroy() 289 290Manually destroyed entities are not removed 291immediately from entities containers like :class:`Modelspace` or 292:class:`EntityQuery`, but iterating such a container will filter destroyed 293entities automatically, so a :code:`for e in msp: ...` loop 294will never yield destroyed entities. The index operator and the :func:`len` 295function do **not** filter deleted entities, to avoid getting deleted entities 296call the :func:`purge` method of the container manually to remove deleted 297entities. 298 299Further Information 300------------------- 301 302- :ref:`reference` documentation 303- Documentation of package internals: :ref:`Developer Guides`. 304