Categories &

Functions List

Function Reference: draw.fromentities

drafting: D = draw.fromentities (E)
drafting: D = draw.fromentities (E, BLOCKS)
drafting: D = draw.fromentities (…, NAME, VALUE, …)
drafting: [D, LOST] = draw.fromentities (…)

Build a drawing from an entity list, as read from a file.

D = draw.fromentities (E) raises the flat entity struct array E into a draw.Drawing, which is what makes a drawing read from a DXF file editable: it can then be transformed, merged into a sheet, dimensioned further and written out again.

D = draw.fromentities (E, BLOCKS) additionally defines the blocks that the INSERT entities of E refer to. BLOCKS is what the fourth output of dxf.read returns. An INSERT naming a block that is not defined is reported rather than guessed at.

This is the inverse of draw.Drawing.entities, and the pair is what makes a file a round trip rather than a one-way door.

Name/Value pairs

'Name'Name for the drawing. Defaults to 'imported'.

Source Code: draw.fromentities

[D, LOST] = draw.fromentities (…) returns what could not be raised, as a struct array with fields index, type and reason, in the same shape draw.Drawing.entities reports its own losses. Nothing is dropped silently.

What comes back, and what cannot

Geometry returns as itself: lines, polylines with their bulges, arcs, circles, text, points, and inserts of the blocks that came with them. A DIMENSION returns as a dimension — its definition points name what it measures, so a linear, angular, diameter or radius dimension is rebuilt as the method that would have made it, and it measures the geometry again rather than repeating a number.

What was lowered on the way out does not come back. A hatch left as its boundary and fill lines, and an ellipse as a sampled polyline; a file records no memory of either having been anything else. They return as the lines and polylines they became. That is a property of the format, not of this function: R12 has no HATCH and no ELLIPSE to record.

So a drawing written and read back is editable geometry, with its dimensions intact and its hatches and ellipses reduced to the marks they made.

See also: draw.Drawing, dxf.read, dxf.write

Source Code: draw.fromentities

A drawing written to a file and read back is a drawing again, not a heap of lines: draw.fromentities is the inverse of entities.

 D = draw.Drawing ('plate');
 D = D.polyline ([0, 0; 100, 0; 100, 60; 0, 60], true).circle ([50, 30], 18);
 D = D.dim ([0, 0], [100, 0], -15, 'horizontal').diam ([50, 30], 18, 45);
 fn = fullfile (tempdir (), 'plate.dxf');
 [E, ~, BL] = entities (D);
 dxf.write (fn, E, 'blocks', BL);
 [R, ~, ~, B] = dxf.read (fn);
 back = draw.fromentities (R, B, 'Name', 'read back')
back =

  draw.Drawing 'read back' with 4 entities on 1 layers
    polyline  1
    circle    1
    dim       1
    current layer: '0'
 delete (fn);

What returned are dimensions, not the lines they were drawn as, so the drawing can go on being edited.

 unique ({back.Entities.type})
ans =
{
  [1,1] = circle
  [1,2] = diam
  [1,3] = dim
  [1,4] = polyline
}

The imported drawing carries on being a drawing: transform it, add to it and write it out again.

 D = draw.Drawing ().polyline ([0, 0; 60, 0; 60, 40; 0, 40], true);
 fn = fullfile (tempdir (), 'part.dxf');
 dxf.write (fn, entities (D));
 back = draw.fromentities (dxf.read (fn));
 delete (fn);
 sheet = back.merge (back.transform ('translate', [80, 0]));
 sheet = sheet.dim ([0, 0], [140, 0], -12, 'horizontal');
 plot (sheet);
 title ('imported once, placed twice, then dimensioned');
plotted figure