Tutorial for Common Graphical Attributes¶

The graphical attributes color, linetype, lineweight, true_color, transparency, ltscale and invisible are available for all graphical DXF entities and are located in the DXF namespace attribute dxf of the DXF entities. All these attributes are optional and all except for true_color and transparency have a default value.

Not all of these attributes are supported by all DXF versions. This table shows the minimum required DXF version for each attribute:

R12	`color`, `linetype`
R2000	`lineweight`, `ltscale`, `invisible`
R2004	`true_color`, `transparency`

Color¶

Please read the section about the AutoCAD Color Index (ACI) to understand the basics.

The usage of the color attribute is very straight forward. Setting the value is:

entity.dxf.color = 1

and getting the value looks like this:

value = entity.dxf.color

The color attribute has a default value of 256, which means take the color defined by the layer associated to the entity. The ezdxf.colors module defines some constants for often used color values:

entity.dxf.color = ezdxf.colors.RED

The ezdxf.colors.aci2rgb() function converts the ACI value to the RGB value of the default modelspace palette.

See also

Basics about AutoCAD Color Index (ACI)
ezdxf.colors module

True Color¶

Please read the section about True Color to understand the basics.

The easiest way is to use the rgb property to set and get the true color values as RGB tuples:

entity.rgb = (255, 128, 16)

The rgb property return None if the true_color attribute is not present:

rgb = entity.rgb
if rgb is not None:
    r, g, b = rgb

Setting and getting the true_color DXF attribute directly is possible and the ezdxf.colors module has helper function to convert RGB tuples to 24-bit value and back:

entity.dxf.true_color = ezdxf.colors.rgb2int(255, 128, 16)

The true_color attribute is optional does not have a default value and therefore it is not safe to use the attribute directly, check if the attribute exists beforehand:

if entity.dxf.hasattr("true_color"):
    r, g, b = ezdxf.colors.int2rgb(entity.dxf.true_color)

or use the get() method of the dxf namespace attribute to get a default value if the attribute does not exist:

r, g, b = ezdxf.colors.int2rgb(entity.dxf.get("true_color", 0)

See also

Basics about True Color
ezdxf.colors module

Transparency¶

Please read the section about Transparency to understand the basics.

It’s recommended to use the transparency property of the DXFGraphic base class. The transparency property is a float value in the range from 0.0 to 1.0 where 0.0 is opaque and 1.0 if fully transparent:

entity.transparency = 0.5

or set the values of the DXF attribute by constants defined in the ezdxf.colors module:

entity.dxf.transparency = ezdxf.colors.TRANSPARENCY_50

The default setting for transparency in CAD applications is always transparency by layer, but the transparency property in ezdxf has a default value of 0.0 (opaque), so there are additional entity properties to check if the transparency value should be taken from the associated entity layer or from the parent block:

if entity.is_transparency_by_layer:
    ...
elif entity.is_transparency_by_block:
    ...
else:
    ...

The top level entity attribute transparency does not support setting transparency by layer or block:

from ezdxf import colors

...

# set transparency by layer by removing the DXF attribute "transparency":
entity.dxf.discard("transparency")

# set transparency by block:
entity.dxf.transparency = colors.TRANSPARENCY_BYBLOCK

# there are also some handy constants in the colors module:
# TRANSPARENCY_10 upto TRANSPARENCY_90 in steps of 10
entity.dxf.transparency = colors.TRANSPARENCY_30  # set 30% transparency
entity.dxf.transparency = colors.OPAQUE

See also

Basics about Transparency
ezdxf.colors module

Linetype¶

Please read the section about Linetypes to understand the basics.

The linetype attribute contains the name of the linetype as string and can be set by the dxf namespace attribute directly:

entity.dxf.linetype = "DASHED"  # linetype DASHED must exist!

The linetype attribute is optional and has a default value of “BYLAYER”, so the attribute can always be used without any concerns:

name = entity.dxf.linetype

Warning

Make sure the linetype you assign to an entity is really defined in the linetype table otherwise AutoCAD will not open the DXF file. There are no implicit checks for that by ezdxf but you can call the audit() method of the DXF document explicitly to validate the document before exporting.

Ezdxf creates new DXF documents with as little content as possible, this means only the resources that are absolutely necessary are created. The ezdxf.new() function can create some standard linetypes by setting the argument setup to True:

doc = ezdxf.new("R2010", setup=True)

See also

Basics about Linetypes
Tutorial for Creating Linetype Pattern

Lineweight¶

Please read the section about Lineweights to understand the basics.

The lineweight attribute contains the lineweight as an integer value and can be set by the dxf namespace attribute directly:

entity.dxf.lineweight = 25

The lineweight value is the line width in millimeters times 100 e.g. 0.25mm = 25, but only certain values are valid for more information go to section: Lineweights.

Values < 0 have a special meaning and can be imported as constants from ezdxf.lldxf.const

-1	LINEWEIGHT_BYLAYER
-2	LINEWEIGHT_BYBLOCK
-3	LINEWEIGHT_DEFAULT

The lineweight attribute is optional and has a default value of -1, so the attribute can always be used without any concerns:

lineweight = entity.dxf.lineweight

Important

You have to enable the option to show lineweights in your CAD application or viewer to see the effect on screen, which is disabled by default, the same has to be done in the page setup options for plotting lineweights.

# activate on screen lineweight display
doc.header["$LWDISPLAY"] = 1

See also

Basics about Lineweights

Linetype Scale¶

The ltscale attribute scales the linetype pattern by a float value and can be set by the dxf namespace attribute directly:

entity.dxf.ltscale = 2.0

The ltscale attribute is optional and has a default value of 1.0, so the attribute can always be used without any concerns:

scale = entity.dxf.ltscale

See also

Basics about Linetypes

Invisible¶

The invisible attribute an boolean value (0/1) which defines if an entity is invisible or visible and can be set by the dxf namespace attribute directly:

entity.dxf.invisible = 1

The invisible attribute is optional and has a default value of 0, so the attribute can always be used without any concerns:

is_invisible = bool(entity.dxf.invisible)

GfxAttribs¶

When adding new entities to an entity space like the modelspace or a block definition, the factory methods expect the graphical DXF attributes by the argument dxfattribs. This object can be a Python dict where the key is the DXF attribute name and the value is the attribute value, or better use the GfxAttribs object which has some additional validation checks and support for code completions by IDEs:

import ezdxf
from ezdxf.gfxattribs import GfxAttribs

doc = ezdxf.new()
msp = doc.modelspace()

line = msp.add_line(
    (0, 0), (10, 10), dxfattribs=GfxAttribs(layer="0", rgb=(25, 128, 16))
)

See also

ezdxf.gfxattribs module