Add a raster IMAGE (DXF Reference) to the DXF file, the file itself is not embedded into the DXF file, it is always a separated file. The IMAGE entity is like a block reference, you can use it multiple times to add the image on different locations with different scales and rotations. But therefore you need a also a IMAGEDEF entity, see ImageDef. ezdxf creates only images in the xy-plan, you can place images in the 3D space too, but then you have to set the Image.dxf.u_pixel and the Image.dxf.v_pixel vectors by yourself.

Subclass of ezdxf.entities.DXFGraphic
DXF type 'IMAGE'
Factory function ezdxf.layouts.BaseLayout.add_image()
Inherited DXF attributes Common graphical DXF attributes
Required DXF version DXF R2000 ('AC1015')


Do not instantiate entity classes by yourself - always use the provided factory functions!

class ezdxf.entities.Image

Insertion point, lower left corner of the image (3D Point in WCS).


U-vector of a single pixel (points along the visual bottom of the image, starting at the insertion point) as (x, y, z) tuple


V-vector of a single pixel (points along the visual left side of the image, starting at the insertion point) as (x, y, z) tuple


Image size in pixels as (x, y) tuple


Handle to the image definition entity, see ImageDef

Image.dxf.flags Value Description
Image.SHOW_IMAGE 1 Show image
Image.SHOW_WHEN_NOT_ALIGNED 2 Show image when not aligned with screen
Image.USE_CLIPPING_BOUNDARY 4 Use clipping boundary
Image.USE_TRANSPARENCY 8 Transparency is on

Clipping state:

0 clipping off
1 clipping on

Brightness value (0-100; default = 50)


Contrast value (0-100; default = 50)


Fade value (0-100; default = 0)


Clipping boundary type:

1 Rectangular
2 Polygonal

Number of clip boundary vertices, maintained by ezdxf.


Clip mode (DXF R2010):

0 Outside
1 Inside

A list of vertices as pixel coordinates, Two vertices describe a rectangle, lower left corner is (-0.5, -0.5) and upper right corner is (ImageSizeX-0.5, ImageSizeY-0.5), more than two vertices is a polygon as clipping path. All vertices as pixel coordinates. (read/write)


Returns the associated IMAGEDEF entity, see ImageDef.

reset_boundary_path() → None

Reset boundary path to the default rectangle [(-0.5, -0.5), (ImageSizeX-0.5, ImageSizeY-0.5)].

set_boundary_path(vertices: Iterable[Vertex]) → None

Set boundary path to vertices. Two vertices describe a rectangle (lower left and upper right corner), more than two vertices is a polygon as clipping path.

boundary_path_wcs() → List[Vec3]

Returns the boundary/clipping path in WCS coordinates.

New in version 0.14.

Since version 0.16 it’s recommended to create the clipping path as Path object by the make_path() function:

form ezdxf.path import make_path

image = ...  # get image entity
clipping_path = make_path(image)
transform(m: Matrix44) → Image

Transform IMAGE entity by transformation matrix m inplace.