1DXF Graphic Entity Base Class
2=============================
3
4.. module:: ezdxf.entities
5    :noindex:
6
7Common base class for all graphical DXF entities.
8
9This entities resides in entity spaces like :class:`~ezdxf.layouts.Modelspace`, any :class:`~ezdxf.layouts.Paperspace`
10or :class:`~ezdxf.layouts.BlockLayout`.
11
12============ =================================
13Subclass of  :class:`ezdxf.entities.DXFEntity`
14============ =================================
15
16.. warning::
17
18    Do not instantiate entity classes by yourself - always use the provided factory functions!
19
20.. class:: DXFGraphic
21
22    .. attribute:: rgb
23
24        Get/set DXF attribute :attr:`dxf.true_color` as ``(r, g, b)`` tuple, returns ``None`` if attribute
25        :attr:`dxf.true_color` is not set.
26
27        .. code-block:: python
28
29            entity.rgb = (30, 40, 50)
30            r, g, b = entity.rgb
31
32        This is the recommend method to get/set RGB values, when ever possible do not use the DXF low level attribute
33        :attr:`dxf.true_color`.
34
35
36    .. attribute:: transparency
37
38        Get/set transparency value as float. Value range ``0`` to ``1``, where ``0`` means entity is opaque and
39        ``1`` means entity is 100% transparent (invisible). This is the recommend method to get/set transparency
40        values, when ever possible do not use the DXF low level attribute :attr:`DXFGraphic.dxf.transparency`
41
42        This attribute requires DXF R2004 or later, returns ``0`` for prior DXF versions
43        and raises :class:`DXFAttributeError` for setting `transparency` in older DXF versions.
44
45    .. automethod:: ocs() -> OCS
46
47    .. automethod:: get_layout() -> BaseLayout
48
49    .. automethod:: unlink_from_layout
50
51    .. automethod:: copy_to_layout(layout: BaseLayout) -> DXFEntity
52
53    .. automethod:: move_to_layout(layout: BaseLayout, source: BaseLayout=None)
54
55    .. automethod:: graphic_properties
56
57    .. automethod:: has_hyperlink
58
59    .. automethod:: get_hyperlink
60
61    .. automethod:: set_hyperlink
62
63    .. automethod:: transform(t: Matrix44) -> DXFGraphic
64
65    .. automethod:: translate(dx: float, dy: float, dz: float) -> DXFGraphic
66
67    .. automethod:: scale(sx: float, sy: float, sz: float) -> DXFGraphic
68
69    .. automethod:: scale_uniform(s: float) -> DXFGraphic
70
71    .. automethod:: rotate_x(angle: float) -> DXFGraphic
72
73    .. automethod:: rotate_y(angle: float) -> DXFGraphic
74
75    .. automethod:: rotate_z(angle: float) -> DXFGraphic
76
77    .. automethod:: rotate_axis(axis: Vec3, angle: float) -> DXFGraphic
78
79.. _Common graphical DXF attributes:
80
81Common graphical DXF attributes
82-------------------------------
83
84    .. attribute:: DXFGraphic.dxf.layer
85
86        Layer name as string; default = ``'0'``
87
88    .. attribute:: DXFGraphic.dxf.linetype
89
90        Linetype as string, special names ``'BYLAYER'``, ``'BYBLOCK'``; default value is ``'BYLAYER'``
91
92    .. attribute:: DXFGraphic.dxf.color
93
94        :ref:`aci`,  default = ``256``
95
96        Constants defined in :mod:`ezdxf.lldxf.const`
97
98        === =========
99        0   BYBLOCK
100        256 BYLAYER
101        257 BYOBJECT
102        === =========
103
104    .. attribute:: DXFGraphic.dxf.lineweight
105
106        Line weight in mm times 100 (e.g. 0.13mm = 13). There are fixed valid lineweights which are accepted by AutoCAD,
107        other values prevents AutoCAD from loading the DXF document, BricsCAD isn't that picky. (requires DXF R2000)
108
109        Constants defined in :mod:`ezdxf.lldxf.const`
110
111        === ==================
112        -1  LINEWEIGHT_BYLAYER
113        -2  LINEWEIGHT_BYBLOCK
114        -3  LINEWEIGHT_DEFAULT
115        === ==================
116
117        Valid DXF lineweights stored in ``VALID_DXF_LINEWEIGHTS``:
118        0, 5, 9, 13, 15, 18, 20, 25, 30, 35, 40, 50, 53, 60, 70, 80, 90, 100, 106, 120, 140, 158, 200, 211
119
120    .. attribute:: DXFGraphic.dxf.ltscale
121
122        Line type scale as float; default = ``1.0`` (requires DXF R2000)
123
124    .. attribute:: DXFGraphic.dxf.invisible
125
126        ``1`` for invisible, ``0`` for visible; default = ``0`` (requires DXF R2000)
127
128    .. attribute:: DXFGraphic.dxf.paperspace
129
130        ``0`` for entity resides in modelspace or a block, ``1`` for paperspace, this attribute is set automatically by
131        adding an entity to a layout (feature for experts); default = ``0``
132
133    .. attribute:: DXFGraphic.dxf.extrusion
134
135        Extrusion direction as 3D vector; default = ``(0, 0, 1)``
136
137    .. attribute:: DXFGraphic.dxf.thickness
138
139        Entity thickness as float; default = ``0.0`` (requires DXF R2000)
140
141    .. attribute:: DXFGraphic.dxf.true_color
142
143        True color value as int ``0x00RRGGBB``, use :attr:`DXFGraphic.rgb` to get/set true color values as ``(r, g, b)``
144        tuples. (requires DXF R2004)
145
146    .. attribute:: DXFGraphic.dxf.color_name
147
148        Color name as string. (requires DXF R2004)
149
150    .. attribute:: DXFGraphic.dxf.transparency
151
152        Transparency value as int, ``0x020000TT`` ``0x00`` = 100% transparent / ``0xFF`` = opaque, use
153        :attr:`DXFGraphic.transparency` to get/set transparency as float value.
154
155        (requires DXF R2004)
156
157    .. attribute:: DXFGraphic.dxf.shadow_mode
158
159        === ==========================
160        0   casts and receives shadows
161        1   casts shadows
162        2   receives shadows
163        3   ignores shadows
164        === ==========================
165
166        (requires DXF R2007)