New 2D Exports

[Paul8043]

This is a question that belongs to issue #75 and PR #190 . I have seen that @jrmobley has contributed a lot of code in this area. I am trying to get my first 2D-export running. I could not find any working example and the new exporters are not yet included in the online documentation. I hope you can give me some start-up aid. This is a very simple example, based on the example 2 (plate with a hole). I take the section at z=0 and would expect to see inside the svg-file a rectangle and a circle. And I have tried to use defaults where ever possible. My m2d.edges() should go the default-layer which is named "". But the code does not run. Let me know what is wrong or missing.

from build123d import *
from build123d import exporters
from ocp_vscode import show, show_object, reset_show, set_port, set_defaults, get_defaults

set_port(3939)

m3d = Box(80,60,20)
m3d -= Cylinder(10,20)
m2d = section(m3d,Plane.XY,height=0)
show_object(m3d,name="m3d",options={"alpha":0.2,"color":(255,170,0)})
show_object(m2d,name="m2d",options={"alpha":0.2,"color":(255,0,0)})

svg = exporters.ExportSVG()
svg.add_shape(m2d.edges(),"")
svg.write("m2d.svg")

[gumyr]

I think you've summed up the situation well. Getting the exports to work (and documented) is one of the last things I'd like to finish before creating the first release. You're example seems like a good place to start; let me see if I can get it to work.

Cheers,
Roger

[jrmobley]

It looks like commit 12504c6 broke the connection between the exporters.LineType enum and ezdxf_linetypes().

https://github.com/gumyr/build123d/blame/01e6d46da606c20bbcf4d45e6d6b96a8cf7d4e3f/src/build123d/exporters.py#L110

@gumyr was cleaning up some pylint issues, so we need to figure out how to make pylint happy but still have the correct values for the enumeration.

Beyond that, call svg.add_shape(m2d) without the .edges() and your test should work. (ExportSVG.add_shape() is expecting a single Shape not a ShapeList.)

[gumyr]

I can't remember why I introduced the change that broke it but I've restored the LineType ENUM and the above example runs now with the following change:

# svg.add_shape(m2d.edges(), "")
for edge in m2d.edges():
    svg.add_shape(edge, "")

Getting unittests for this new exporter code needs to be complete before the release can be done.

[Paul8043]

Hi @jrmobley,
First let me give you some background information. I came from OpenSCAD over CadQuery to Build123. All 3 are great applications and Build123d is the leader, it has a very clear structure and it is easy to use. So, I am trying to port some of my older models to Build123d, just to see how well it works, and it does. I do 3D-printing with STL-files which works with Build123d without any problems. My second application is wood-working with a "Handheld Precision Router" see here. This is a very interesting machine. This machine understands natively SVG-files (no CAM needed). This explains why I am so much interested in SVG-Files. In principle I could load the outcome of a section() into the router and then I could cut line by line. But the router does not think in "lines", it thinks in "wires". The "edge soup" you mentioned can be loaded into the router, but working with individual edges is a pain and very time consuming. To get the full power of the router the contours must be given as closed lines (wires). The color-encoding of the wires determines where to cut details are given here. You can cut directly on the line, outside or inside, or make a pocket. So, the idea is to set up an individual layer for each cut-type. This is the reason why I have to partition the "edge soup". For add_shape() it would be most comfortable, if it accepts anything that is flat (lives in a 2D plane), including 2D-components!
My next step is to check whether all needed SVG-attributes (color,stroke,fill,etc) can be given during the add_layer()-call, could be that there is some need for a more agile dictionay-interface.
Next week I will check some real-world examples.
Again, thanks a lot for providing ExportSVG.

[jrmobley]

Ah, I understand. You don't want to break the section down into edges, you want to break it into wires and put the wires on different layers. That makes perfect sense.

I am doing some research and experiments right now to figure out how to process a wire correctly so that a single path could be written to the SVG. This is getting into some new, low-level OCP territory for me, so it may take me a while.

Regarding the layers and attributes, like color, etc., the API is modeled after the DXF feature set, so if it seems a little strange, that is why. I was trying to keep the two formats in parity with as much as possible the same visual results. You will find color and stroke options, but not fill. I think the best that DXF can do there is a hatch pattern.

I see that fill color is important for your router, so I will also look to add it to ExportSVG, even if ExportDXF can't support it.

It also looks like your router might require a specific RGB for blue? I will need to expand the API for that a little bit as well.

For add_shape() it would be most comfortable, if it accepts anything that is flat (lives in a 2D plane), including 2D-components!

It should already accept anything 2D, no matter how you create it. All that it currently does is grab all the edges of whatever you pass in, so it is very accepting in that way.

[jrmobley]

I have some promising early results:

<?xml version='1.0' encoding='utf-8'?>
<svg width="80.09mm" height="60.09mm" viewBox="-40.045 -30.045 80.09 60.09" version="1.1" xmlns="http://www.w3.org/2000/svg">
  <g transform="scale(1,-1)" stroke-linecap="round">
    <g stroke="rgb(0,0,0)" stroke-width="0.09" fill="none">
      <path d="M 40.0,30.0 L -40.0,30.0 L -40.0,-30.0 L 40.0,-30.0 L 40.0,30.0" />
      <circle cx="0.0" cy="0.0" r="10.0" />
    </g>
  </g>
</svg>

Plenty of work left to do. I really must create some specific test cases to exercise all the possibilities.

[Paul8043]

I see that fill color is important for your router, so I will also look to add it to ExportSVG, even if ExportDXF can't support it.

You are absolutely right, fill-color is important for my router.

It also looks like your router might require a specific RGB for blue? I will need to expand the API for that a little bit as well.

This is also true. The 4 relevant colors are:
#000000 black
#FFFFFFF white
#7F7F7F grey
#0068FF light blue
The best would be an interface that would allow to enter arbitrary RGB-values.
Some more explanations related to cut-types: Interior cut, exterior cut, on line cut are line-cuts, whereas the pocketing cut is a area-cut (the entire grey area is cut out). The last one called "guide" is also related to an area, but here the area is an exclusion zone, the router should never enter into this area.

Sections, even complex ones, probably maintain decent structure.

This is also good news. If we could partition the edges into wires, this would make a great contribution. It will simplify the routing-operations significantly!

I have some promising early results:

I have loaded your early results into my router. The file was accepted without any complaints. And it was a wire, not 4 individual edges! Your are on the right track.

For the path-statement there exist to different encodings, the one you have used:
<path d="M 40.0,30.0 L -40.0,30.0 L -40.0,-30.0 L 40.0,-30.0 L 40.0,30.0" />
and second one which is a little bit more compact:
<path d="M 40.0,30.0 L -40.0,30.0 L -40.0,-30.0 L 40.0,-30.0 Z" />
Both are equalivent, but the last one avoids the repeating of the first coordinate-pair, no need to store the first coordinate-pair, just add a " Z" at the end and your are done.

[Paul8043]

This is just a code cleanup to the extent of what we have up-to-now (2 layers, stroke & fill colors given as comment, w1 approximated by e0,e1,e2,e3)

from build123d import *
from build123d.exporters import *
from ocp_vscode import show, show_object, reset_show, set_port, set_defaults, get_defaults

set_port(3939)

m3d = Box(80,60,20)
m3d -= Cylinder(10,20)
m2d = section(m3d,Plane.XY,height=0)
show_object(m3d,name="m3d",options={"alpha":0.2,"color":(255,170,0)})
show_object(m2d,name="m2d",options={"alpha":0.2,"color":(255,0,0)})

for edge in m2d.edges():
    print(f"{edge.geom_type()=}")

edges = m2d.edges()
w1 = [edge for edge in edges if edge.geom_type() == "LINE"]
w2 = [edge for edge in edges if edge.geom_type() == "CIRCLE"]

svg = ExportSVG(unit=Unit.MILLIMETER,scale=1,margin=10,line_weight=0.1)
svg.add_layer("exterior-cut")             # should set stroke="#000000" & fill="#000000"
for edge in w1:
    svg.add_shape(edge,"exterior-cut")
svg.add_layer("interior-cut")             # should set stroke="#000000" & fill="#FFFFFF"
for edge in w2:
    svg.add_shape(edge,"interior-cut")
svg.write("m2d.svg")

[Paul8043]

I just want to give you more practical example. It is a real part from one of my models. Here the model is built bottom-up. It starts wirth line-segments. The line-segments are put into closed polylines. Each polyline represents a wire. And with the polylines some faces are created, and with them the final 3D-model is extruded. I have given this example, because making a section of a 3D-model is not always the best choice to retrieve information for a router. Sometimes the router needs a few more lines. In this case the cutting can be done with the 3 red rectangles, the inner 2 overlap each other (best seen with top-view). The good news is, the new ExportSVG can also handle 1D-objects, which is great! So, it seems, this example does not introduce new difficulties. The task remains as before, how to partition the edge-soup into more useful wires.

from build123d import *
from build123d.exporters import *
from ocp_vscode import show, show_object, reset_show, set_port, set_defaults, get_defaults

set_port(3939)

name="jamb_side"
margin=15
overhang=5
length=100
width=50
thickness=18
cut_width=15
cut_depth=30
cut_air=5
pts = [
    (0,0),                                              # P0   unused
    (+0.5*width,0),                                     # P1   raw plate
    (+0.5*width,length),                                # P2   raw plate
    (-0.5*width,length),                                # P3   raw plate
    (-0.5*width,0),                                     # P4   raw plate
    (-0.5*cut_width-cut_air,length-cut_depth-cut_air),  # P5   cut-off
    (-0.5*cut_width-cut_air,length+overhang+cut_air),   # P6   cut-off
    (+0.5*cut_width+cut_air,length+overhang+cut_air),   # P7   cut-off
    (+0.5*cut_width+cut_air,length-cut_depth-cut_air),  # P8   cut-off
    (+0.5*width+margin,0-margin),                       # P9   border
    (+0.5*width+margin,length+margin),                  # P10  border
    (-0.5*width-margin,length+margin),                  # P11  border
    (-0.5*width-margin,0-margin),                       # P12  border
]
border_pts = [pts[9],pts[10],pts[11],pts[12]]
plate_pts  = [pts[1],pts[2],pts[3],pts[4]]
cut_pts    = [pts[5],pts[6],pts[7],pts[8]]
border_pl  = Polyline(*border_pts,close=True)
plate_pl   = Polyline(*plate_pts,close=True)
cut_pl     = Polyline(*cut_pts,close=True)
m1d        = Curve()+[border_pl,plate_pl,cut_pl]       
border_fc  = make_face(Plane.XY*border_pl)
plate_fc   = make_face(Plane.XY*plate_pl)
cut_fc     = make_face(Plane.XY*cut_pl)
m2d_full   = Sketch()+plate_fc
m2d_cut    = Sketch()+plate_fc-cut_fc
m3d_full   = Part()+extrude(m2d_full,-0.5*thickness,both=True)  
m3d_cut    = Part()+extrude(m2d_cut,-0.5*thickness,both=True)

show_object(m3d_cut,name="m3d_cut_"+name,options={"alpha":0.2,"color":(255,170,0)})
show_object(m1d,name="m1d_"+name,options={"alpha":0.2,"color":(255,0,0)})

for edge in m1d.edges():
    print(f"{edge.geom_type()=}")

svg = ExportSVG(unit=Unit.MILLIMETER,scale=1,margin=10,line_weight=0.1)
for edge in m1d.edges():
    svg.add_shape(edge,"")
svg.write("m1d.svg")

[jrmobley]

I have tried to run it, but it seems that this code has not yet been released to the public. I fully understand, if you wait until everything is complete.

Yeah, I need to finish up everything, including at least some contribution to the unit tests, and then submit a pull request to @gumyr for evaluation and merging.

How can I get orphaned edges, edges that do not belong to any wires? This is a common use case, e.g. if some cross-hairs ared added to help aligning the workpart.

I am processing edges in two groups. For the first group, I get all of the wires found in the shape, then process their edges in a topological loop, creating a single path element for each wire. For the second group, I find all of the edges that are not associated with a wire and create an SVG element for each of these loose edges. So your orphaned edges should come out just fine.

But what should we do, if the order (direction) of the path (wire) is not correct. Because of that I would suppose to introduce an additional parameter for add_shape called flip_wire_direction like this svg.add_shape(wire, "interior", flip_wire_direction=True) .

I will look into ways to deal with this. I would like to find a method to reverse a face geometrically instead of trying to traverse the wire backwards, which would actually be rather messy.

Have you already tried to run my second example?

I have run it as-is, but it was not immediately clear to me how you mean to assign border_fc, plate_fc, and cut_fc to the layers, so I did not try to re-factor it.

[Paul8043]

I have tried to polish my example-1. I just wanted to add a cross-hair to the section. Thought this should be a simply task, but it is not! The code below does not work. I got irritated, too many unexpected things. Why is the result of a section() a part? Would have expected to see a 2D-object, probably a sketch. And why it is not allowed to add lines (1D-objects) to a higher dimensional space? Seems I am on a completely wrong track! Let me know how the two lines can be added to m2d.

from build123d import *
from build123d.exporters import *
from ocp_vscode import show, show_object, reset_show, set_port, set_defaults, get_defaults

set_port(3939)

m3d = Box(80,60,20)
m3d -= Cylinder(10,20)
m2d = section(m3d,Plane.XY,height=0)

l1  = Line((-5,0),(+5,0))
l2  = Line((0,-5),(0,+5))
m2d += [l1,l2]                           # add cross-hair

#show_object(m3d,name="m3d",options={"alpha":0.2,"color":(255,170,0)})
show_object(m2d,name="m2d",options={"alpha":0.2,"color":(255,0,0)})

[gumyr]

section should generate a Sketch not a Part (it's an exception). Algebra limits combination of objects of different dimensions to avoid strange scenarios where one attempts to extrude a Solid. In this case, a 1 dimensional Line is being added to a 2 dimensional Sketch which is not allowed. Creating a drawing with both 1D and 2D objects is clearly desirable - can't they be added as separate objects?

[gumyr]

Looking at section again reminded my why it generates a Part not a Sketch - one can pass multiple Planes to it therefore generating multiple 2D Sketches. This is useful if one wants to generate ribs from a 3D object.

[Paul8043]

can't they be added as separate objects?

I am always willing to accept alternatives. At the moment I cannot see how a solution with separate objects will look like? Can you show this for the example above? The point here is that the cross-hair has a close relationship to the wires, they form one unit!

Looking at section again reminded my why it generates a Part not a Sketch - one can pass multiple Planes to it therefore generating multiple 2D Sketches. This is useful if one wants to generate ribs from a 3D object.

If this is the case, then section() should return a list of 2D-Sketches and not a Part. In all circumstances there must be clear ways how to jump over the dimensional boundaries. extrude() converts 2D to 3D, I had hoped that section() does the opposit (3D to 2D).

Working with BuildLine, BuildSketch and BuildPart is a solid basis. But real applications go beyond, they need the combination. The 3D-space needs to be populated with all 3 of them, meaning a BuildPart may include BuildSketches and even BuildLines, and same way a BuildSketch may include BuildLines. This stuff is very difficult to understand.

[Paul8043]

Example-1:
This is the polished version of example-1. m2d.wires() is correctly populated, which means that we can iterate directly over wires instead of faces. For the long term add_shape() should be tolerant as show_results(), it should take what fits. In this example the focus is on wires, therefore we are looping over wires, so that each wire can get the needed attributes (stroke-color, fill-color, wire_direction).

from build123d import *
from build123d.exporters import *
from ocp_vscode import show, show_object, reset_show, set_port, set_defaults, get_defaults

set_port(3939)

m3d = Box(80,60,20)
m3d -= Cylinder(10,20)
m2d = section(m3d,Plane.XY,height=0)

# some fact findings

print(f"#solids={len(m2d.solids())}")
for idx, solid in enumerate(m2d.solids()):
    print(f"solids[{idx}]={solid}")
print(f"#faces={len(m2d.faces())}")    
for idx, face in enumerate(m2d.faces()):
    print(f"faces[{idx}]={face}")
print(f"#wires={len(m2d.wires())}")    
for idx, wire in enumerate(m2d.wires()):
    print(f"wires[{idx}]={wire}")
print(f"#edges={len(m2d.edges())}")
for idx, edge in enumerate(m2d.edges()):
    print(f"edges[{idx}]={edge}")
print(f"#vertices={len(m2d.vertices())}")    
for idx, vertex in enumerate(m2d.vertices()):
    print(f"vertices[{idx}]={vertex}")

#show_object(m3d,name="m3d",options={"alpha":0.2,"color":(255,170,0)})
show_object(m2d,name="m2d",options={"alpha":0.2,"color":(0,0,0)})
show_object(m2d.wires()[0],name="wires()[0]",options={"alpha":0.2,"color":(255,0,0)})  # rectangle
show_object(m2d.wires()[1],name="wires()[1]",options={"alpha":0.2,"color":(255,0,0)})  # circle

#svg = ExportSVG()
#white = (255,255,255)
#black = (0,0,0)
#gray = (127,127,127)
#blue = (0,104,255)
#svg.add_layer("exterior", line_color=black, fill_color=black)
#svg.add_layer("pocketing", fill_color=gray)
#svg.add_layer("interior", line_color=black, fill_color=white)
#svg.add_layer("on-line", line_color=gray)
#svg.add_layer("guide", line_color=blue)
#svg.add_shape(m2d.wires()[0], "exterior")   # rectangle
#svg.add_shape(m2d.wires()[1], "interior")   # circle
#svg.write("example-1-v02.svg")

[Paul8043]

Example-2:
This example has been built bottom-up. From the program we have 3 closed polylines where each one has the shape of a rectangle. Note, the inner two polylines overlap. m1d.wires() contains only 2 entries which seems to be wrong, it should be 3! This example has wires, but no faces! This means the under-the-hood-logic of example-1 to derive wires from faces is probably not called. This is a strong indicator that the internal logic should be based on wires, not on faces.

Any ideas why we have got only 2 wires instead of 3? The 3 polylines, verified with show_object(), are correct. I think this line
m1d = Curve()+[border_pl,plate_pl,cut_pl]
is the problem. Is there an operator which just allows to compose the 3 polylines, without any fusing? The question behind is how to make a composition of objects in algebra-mode. The 3 polylines have to go somehow into m1d. Only then I can expect that the selector-lists (e.g. m1d.wires()) contain the right information?

from build123d import *
from build123d.exporters import *
from ocp_vscode import show, show_object, reset_show, set_port, set_defaults, get_defaults

set_port(3939)

margin=15
overhang=5
length=100
width=50
thickness=18
cut_width=15
cut_depth=30
cut_air=5
pts = [
    (0,0),                                              # P0   unused
    (+0.5*width,0),                                     # P1   raw plate
    (+0.5*width,length),                                # P2   raw plate
    (-0.5*width,length),                                # P3   raw plate
    (-0.5*width,0),                                     # P4   raw plate
    (-0.5*cut_width-cut_air,length-cut_depth-cut_air),  # P5   cut-off
    (-0.5*cut_width-cut_air,length+overhang+cut_air),   # P6   cut-off
    (+0.5*cut_width+cut_air,length+overhang+cut_air),   # P7   cut-off
    (+0.5*cut_width+cut_air,length-cut_depth-cut_air),  # P8   cut-off
    (+0.5*width+margin,0-margin),                       # P9   border
    (+0.5*width+margin,length+margin),                  # P10  border
    (-0.5*width-margin,length+margin),                  # P11  border
    (-0.5*width-margin,0-margin),                       # P12  border
]
border_pts = [pts[9],pts[10],pts[11],pts[12]]
plate_pts  = [pts[1],pts[2],pts[3],pts[4]]
cut_pts    = [pts[5],pts[6],pts[7],pts[8]]
border_pl  = Polyline(*border_pts,close=True)
plate_pl   = Polyline(*plate_pts,close=True)
cut_pl     = Polyline(*cut_pts,close=True)
m1d        = Curve()+[border_pl,plate_pl,cut_pl]     

# some fact findings

print(f"#solids={len(m1d.solids())}")
for idx, solid in enumerate(m1d.solids()):
    print(f"solids[{idx}]={solid}")
print(f"#faces={len(m1d.faces())}")
for idx, face in enumerate(m1d.faces()):
    print(f"faces[{idx}]={face}")
print(f"#wires={len(m1d.wires())}") 
for idx, wire in enumerate(m1d.wires()):
    print(f"wires[{idx}]={wire}")
print(f"#edges={len(m1d.edges())}")
for idx, edge in enumerate(m1d.edges()):
    print(f"edges[{idx}]={edge}")
print(f"#vertices={len(m1d.vertices())}")
for idx, vertex in enumerate(m1d.vertices()):
    print(f"vertices[{idx}]={vertex}")

show_object(m1d,name="m1d",options={"alpha":0.2,"color":(255,170,0)})
#show_object(m1d.wires()[0],name="wires()[0]",options={"alpha":0.2,"color":(255,0,0)})
show_object(m1d.wires()[1],name="wires()[1]",options={"alpha":0.2,"color":(255,0,0)})
#show_object(border_pl,name="border_pl",options={"alpha":0.2,"color":(255,0,0)})
#show_object(plate_pl,name="plate_pl",options={"alpha":0.2,"color":(255,0,0)})
#show_object(cut_pl,name="cut_pl",options={"alpha":0.2,"color":(255,0,0)})

svg = ExportSVG()
#white = (255,255,255)
#black = (0,0,0)
#gray = (127,127,127)
#blue = (0,104,255)
#svg.add_layer("exterior", line_color=black, fill_color=black)
#svg.add_layer("pocketing", fill_color=gray)
#svg.add_layer("interior", line_color=black, fill_color=white)
#svg.add_layer("on-line", line_color=gray)
#svg.add_layer("guide", line_color=blue)
svg.add_shape(m1d.wires()[0], "")
svg.add_shape(m1d.wires()[1], "")
svg.write("example-2-v01.svg")

[gumyr]

What you're looking for here is a Compound/assembly. This is a collection of objects that aren't fused together - like this:

border_pl.label = "border"
plate_pl.label = "plate"
cut_pl.label = "cut"
drawing = Compound(label="drawing", children=[border_pl, plate_pl, cut_pl])
print(drawing.show_topology())
show_object(drawing, name="drawing")
svg = ExportSVG()
svg.add_shape(drawing, "")
svg.write("example-2-v01.svg")

drawing    Compound at 0x7f02f6ff3c10, Location(p=(0.00, 0.00, 0.00), o=(-0.00, 0.00, -0.00))
├── border Polyline at 0x7f0376ad0fd0, Location(p=(0.00, 0.00, 0.00), o=(-0.00, 0.00, -0.00))
├── plate  Polyline at 0x7f02f700f070, Location(p=(0.00, 0.00, 0.00), o=(-0.00, 0.00, -0.00))
└── cut    Polyline at 0x7f02f7001d00, Location(p=(0.00, 0.00, 0.00), o=(-0.00, 0.00, -0.00))

The svg looks fine in Inkscape:

[jrmobley]

Also, in this particular example, it might be simplest to skip making a compound:

svg.add_shape(border_pl, "guide")
svg.add_shape(plate_pl, "exterior")
svg.add_shape(cut_pl, "interior")

(I am just guessing about the layer assignments.)

-- edit: replace PNG with SVG --

[Paul8043]

@gumyr
Thanks a lot for both solutions. The last one I have discovered by myself during late last night! add_shape() can accept data from different models or objects. And your guessing about the layers is correct. Sometimes the solutions come from a totally unexpected corner. Practice makes perfect. Nothing counts more than own experiences. You can be sure, everything is memorized, I will never forget these solutions.

[Paul8043]

You see I work hard to develop the right understanding of the things. With this additional knowledge I have tried to design an example which should have orphaned edges (those which do not belong to a wire). I took the example "plate-with-hole" and added a cross-hair in the center of the plate. The Compund seems to be perfect candidate for this purpose.

# example-1a.py

from build123d import *
from build123d.exporters import *
from ocp_vscode import show, show_object, reset_show, set_port, set_defaults, get_defaults

set_port(3939)

m3d = Box(80,60,20)
m3d -= Cylinder(10,20)
m2d = section(m3d,Plane.XY,height=0)
m2d.label = "m2d"
l1 = Line((-5,0),(+5,0))     # horizontal line
l1.label = "l1"
l2 = Line((0,-5),(0,+5))     # vertical line
l2.label = "l2"

drawing = Compound(label="drawing", children=[m2d, l1, l2])
print(drawing.show_topology())

# some fact findings

print(f"#solids={len(drawing.solids())}")
for idx, solid in enumerate(drawing.solids()):
    print(f"solids[{idx}]={solid}")
print(f"#faces={len(drawing.faces())}")
for idx, face in enumerate(drawing.faces()):
    print(f"faces[{idx}]={face}")
print(f"#wires={len(drawing.wires())}") 
for idx, wire in enumerate(drawing.wires()):
    print(f"wires[{idx}]={wire}")
print(f"#edges={len(drawing.edges())}")
for idx, edge in enumerate(drawing.edges()):
    print(f"edges[{idx}]={edge}")
print(f"#vertices={len(drawing.vertices())}")
for idx, vertex in enumerate(drawing.vertices()):
    print(f"vertices[{idx}]={vertex}")

show_object(drawing,name="drawing",options={"alpha":0.2,"color":(255,170,0)})
show_object(drawing.wires()[0],name="wires[0]",options={"alpha":0.2,"color":(255,0,0)})
show_object(drawing.wires()[1],name="wires[1]",options={"alpha":0.2,"color":(255,0,0)})
show_object(drawing.wires()[2],name="wires[2]",options={"alpha":0.2,"color":(255,0,0)})
show_object(drawing.wires()[3],name="wires[3]",options={"alpha":0.2,"color":(255,0,0)})

svg = ExportSVG()
svg.add_layer("exterior")
svg.add_layer("pocketing")
svg.add_layer("interior")
svg.add_layer("on-line")
svg.add_layer("guide",)
svg.add_shape(drawing.wires()[0], "exterior")   # rectangle
svg.add_shape(drawing.wires()[1], "interior")   # circle
svg.add_shape(drawing.wires()[2], "guide")      # l1
svg.add_shape(drawing.wires()[3], "guide")      # l2
svg.write("example-1a.svg")

I had hoped to get still 2 wires and 2 additional orphaned edges. But the reality tells another story.

drawing  Compound at 0x1d9f24bf3d0, Location(p=(0.00, 0.00, 0.00), o=(-0.00, 0.00, -0.00))
├── m2d  Part     at 0x1d9f274ad50, Location(p=(0.00, 0.00, 0.00), o=(-0.00, 0.00, -0.00))
├── l1   Line     at 0x1d9f183bfd0, Location(p=(0.00, 0.00, 0.00), o=(-0.00, 0.00, -0.00))
└── l2   Line     at 0x1d9eb4f4690, Location(p=(0.00, 0.00, 0.00), o=(-0.00, 0.00, -0.00))

#solids=0
#faces=1
faces[0]=<build123d.topology.Face object at 0x000001D9F24FE890>
#wires=4
wires[0]=<build123d.topology.Wire object at 0x000001D9EA2A4D10>
wires[1]=<build123d.topology.Wire object at 0x000001D9F27CBED0>
wires[2]=<build123d.topology.Wire object at 0x000001D9F27CBF50>   # <== unexpected
wires[3]=<build123d.topology.Wire object at 0x000001D9F27CBF10>   # <== unexpected
#edges=7
edges[0]=<build123d.topology.Edge object at 0x000001D9EA2A4D10>
edges[1]=<build123d.topology.Edge object at 0x000001D9F27CBED0>
edges[2]=<build123d.topology.Edge object at 0x000001D9F27CBF50>
edges[3]=<build123d.topology.Edge object at 0x000001D9E3ADCE90>
edges[4]=<build123d.topology.Edge object at 0x000001D9F27D8150>
edges[5]=<build123d.topology.Edge object at 0x000001D9F27D8050>
edges[6]=<build123d.topology.Edge object at 0x000001D9F27D8110>
#vertices=9
vertices[0]=Vertex: (-40.0, 30.0, 0.0)
vertices[1]=Vertex: (40.0, 30.0, 0.0)
vertices[2]=Vertex: (40.0, -30.0, 0.0)
vertices[3]=Vertex: (-40.0, -30.0, 0.0)
vertices[4]=Vertex: (10.0, -2.4492935982947065e-15, 0.0)
vertices[5]=Vertex: (-5.0, 0.0, 0.0)
vertices[6]=Vertex: (5.0, 0.0, 0.0)
vertices[7]=Vertex: (0.0, -5.0, 0.0)
vertices[8]=Vertex: (0.0, 5.0, 0.0)

l1 and l2, each of them, has been packed in a separate wire! This is unexpected behavior to me and I am sure there a good reasons for this choice. However, as a wood-worker, I have to develop the proper understanding of wires. I thought by definition a wire is a closed line, but l1 and l2 are straight lines (not closed). It seems that we can have degenerated wires. A closed wire can have a direction. In QCAD a closed polyline has an direction-attribute which can have the value clockwise or counter-clockwise.

The question is, in OCP does a wire have a similiar attribute? @gumyr can you give the answer?

If yes, this is a valuable information. In this case the we can directly specify in add_shape() the wire_direction, otherwise we can only offer to flip_wire_direction, if needed. I just wanted to make sure that my router does not get unexpected values. Sorry, if I have stressed this issue too much. But a solid investigation is the basis for a solid and robust solution.

BTW, I am not upset, if orphaned edges do not exist, quite the contrary!

[jrmobley]

I am also surprised that the guide lines turned into non-closed wires. The exporter doesn't mind though.

[jrmobley]

Progress Report:
I have finished wire support for all types of edge geometry: lines, circles, ellipses, and splines (which handle everything else). After some refactoring, I was able to implement a reverse_wires option fairly elegantly, so that is done now. I am building up a set of test cases to cover the different code paths, but I am still relying on manual inspection of the results.

[Paul8043]

@jrmobley

Thanks for keeping me up-to-date.

I am probably not explaining that very well, but basically I don't think I can support a wire_direction option, only a flip_wire_direction option, despite the availability of the wire orientation property, because I don't know outer wires from inner wires.

I fully understand this, a flip_wire_direction is easier to realize.

I was able to implement a reverse_wires option fairly elegantly, so that is done now.

These are very good news.

If you would like, I can help you with the manual inspection of the svg-files (checking them on my router). And hopefully I find some time to create additional test-cases.

At the moment my head is full of edges and wires.

[Paul8043]

@gumyr

A build123d-model interacts with me by presenting flat soup-lists for the selectors. They might be sufficient for running selectors, but they are not so useful, if you try to understand the pieces of the model. All the context information is gone and you never know which index belongs to which aspect.

The add_shape() is similiar to show_object(). For both some knowledge is needed from the OCP-world. You work hard to keep the things simple on Build123d-level. And in most case I can take Build123d as a black-box without worrying too much about internals. But, as very often, you cannot run the black-boxes in the right way, if don't have a adequate understanding in your mind.

At the moment I stumble from one thing to the next. I am confronted with unexpected behavior and first I have to learn how the things behave! This is reason why the discussion about wire-direction takes a little bit longer. Better to spend more time now, instead to allow a wrong conception in my mind.

It looks like the top circle is both - weird!

I would say the whole cube looks weird. It should be not possible that a wire can have edges with different directions as is does on the left face. Some of the weirdness might come from show_object(), because show_object() might be called several times for the same edge and only the last call survives in the picture!

The point is, for a cube each edge belongs to 2 faces and therefore to 2 wires. You can define a wire_direction property and you can define that the edges of wire should adopt the direction. So far so good. For the next wire you can set the direction to an arbitrary value, and if this wire shares an edge of the previous one, we can reach contradictory conditions. The means you can define a static direction for a wire, but not for a edge. The direction of an edge may change on context (wire).

Ok, this is guesswork from my mind, based on the knowledge I have absorbed so far.

Can an edge belong to more than one wire?

I can be completely wrong. You see there is some need to clarify these things.

My approach was, just ask what kind of information is available from th OCP-world and take what might be of value for generating of svg-files than can drive a router. I have already tried a lot of different applications, even those that the manufacturer of router has recommendend, but none of them works flawlessly. With Build123d we are able to change this, we can make a svg-file which is router-qualified.

I have the impression that we should verify, if your understanding of w.is_forward is in accordance with my understanding of wire_direction. Is there a definition of w.is_forward?

Give me a few hours and I will come up with some illustrations.

[Paul8043]

Let us go back to example-1:

closed-wire-simple
Here the router walks along the red line. For the inner_wire the direction is CW (clockwise). For the outer_wire the direction CCW (counterclockwise). If the wire has a simple shape, it is easy to recognize the direction.

closed-wire-complex
The router still walks along the read line. Even the router makes some left and right turns, this does not have any impact on the direction. The direction is same as in the previous illustration. A human eye can see the direction immediately. But if you try to derive the direction from the list of x/y-coordinates, this might be a challenge. At the moment I do not know a simple algorithm for this.

Be aware that the wire-direction is only needed inside the call of add_shape() and there only for the wire in process.

To make this simpler, imagine that a wire looks like a pearl necklace where the pearls are labelled with single letters. The necklace might have an arbitrary shape, but the whole thing lives in the XY-plane. Your view-point is the top of the Z-axis and then you look downwards. Then you stretch the necklace to a circle and then you can immediately recognize the direction (CC or CCW). This is sketched below:
bird-view

The next thing is how to convert a closed wire to a svg-path-list? This is sketched here:
alternatives for a closed wire
For the example with 5 pearls there are 10 alternatives which produce exactly the same rendered output (the line seen in the browser). You can start with any pearl (5 choices) and you have 2 directions.
So, @jrmobley could select any of the 10 alternatives, that does not matter. He can take the simplest to implement, or the keep the old code. It is only important that the svg-path is closed, this can be achieved by repeating the first coordinate at the end. This is the reason why the svg-path has 6 elements for necklace of 5 pearls. If we take the old code, we do not know which direction was realized, it could be CC or CCW. But this not problem, if we can reverse svg-path-list later on. The operation is simple, just drop the last element, reverse the list, and add the first element at the very end.

alternatives for open wire
Here we have only 2 alternatives and the flip-operation is simpler, just reverse the list.

We can apply occam's razor: We should not the make the solution more complicated than necessary. The svg-file can be made router-compliant with only little code modifications. I hope @jrmobley can confirm this. I personally do not see any need to introduce a direction-property for a wire. I tend to select the simplest solution, and this solution makes already a great contribution.

One thing is left over:
You cannot easily see which direction has been taken for the svg-output. If we could replace temporarily a line inside the svg by an arrow, then we could see the direction, but this is not easy doing. But this is only a minor limitation, the router can do air-cuts, where the spindle remains in up-position. So, the moving-direction can be checked in advance without any impact on the workpart.

[jrmobley]

I believe that ExportSVG now has all the tools that you need. (After @gumyr integrates the PR.)

The winding order produced by OCCT is very consistent, so even without a visualization aid (like arrows) you should be able to predict the outcome. Most operations are going to produce outer wires with CCW winding, and inner wires with CW winding, when viewed from the +Z axis, just as in your notes above. I only encountered one exception in my tests: If you take a section co-planar with a "backward facing" face, then the section will contain that backward facing geometry. This in in contrast to sections through the body of a solid, which create forward facing (+Z normal) faces. Purely 2D constructions are forward facing.

On the topic of sections, here is an example of how I produce them.

section_plane = Plane.XZ.offset(4)
conic_section = section_plane.to_local_coords(section(cone, section_plane))

The call to Plane.to_local_coords is important to move the section onto the XY plane for export. Of course, if you take a section through the XY plane itself, with no offsets, then this step is unnecessary.

[Paul8043]

I believe that ExportSVG now has all the tools that you need. (After @gumyr integrates the PR.)

Thanks to both of you.

Then it looks that the wire windings of OCCT will fit in most cases for my router. This is good news.

[jrmobley]

Purely 2D constructions are forward facing.

I have just learned from experience that you do need to be careful when building 2D shapes from lines. I find that you have control of the winding order and if you specify your shape in CW order, then you will get a backward facing, CW wound result. So watch out for that.

[Paul8043]

Thanks for your additional hints.

[gumyr]

This whole discussion is very interesting but not what I originally expected. Normally CNC Routers would operate from g-code which has been developed over the last 60 or so years to exactly this purpose. Running a CNC Router off standard SVG is interesting but I wonder if it's a sufficiently capable solution. Within build123d and OpenCascade Edge and Wire direction is defined by the topology of the objects, not by any external constraints like spindle rotations. What is the line between drawing and CAM?

[jrmobley]

It is an odd case. This router has a built-in equivalent to a g-code processor, but it seems to be severely limited to the point where, as you say, the drawing starts to become a CAM file. I have to wonder how the user base of this router produces their drawings, in general. Obvs, we know how @Paul8043 is doing it. 😆

Happily, I feel like the features I have added in support of this case are good features generally as well. Only the wire reversal option smells a bit, but it did turn out to be a very small addition.

How much of this can be applied to the DXF exporter? Not fill colors as far as I know. As for the wires, it looks to me like a polygon or polyline is the closest thing that DXF supports, and that is limited to straight lines and circular arcs, so support would only be available for certain geometries, and not in the general case.

[Paul8043]

@gumyr
You are right, normally CNC-Routers are driven by G-Code. But my router is an exception. The native language of the router is SVG, not G-Code, and the router talks only SVG and nothing else. This device is primarily used to build prototypes and jigs. And for this purpose it is really a good choice. I do not know why SVG was the winner. But I could imagine that they thought a simple drawing program would be easiest to use and everbody can take its favorite program. The advantage is the tool-chain has the length 1, only a single tool is needed. For most other solutions with genuine CAM-Tools the tool-chain is much longer and more difficult to use. And this router should be runnable by persons without deep CAD-background.

In general this approach works quite well. Most projects can be performed without any trouble. But there are a few corner case, where the SVG-approach reveals some deficiencies. Sometimes the cut-direction was wrong and I could not find out why. Only after working with some CAD-Tools (CadQuery & Build123d) I was able to identify the root-cause and how the short-comings could be resolved.

@jrmobley

Only the wire reversal option smells a bit

I know, but only a little bit!

[gumyr]

A build123d-model interacts with me by presenting flat soup-lists for the selectors. They might be sufficient for running selectors, but they are not so useful, if you try to understand the pieces of the model. All the context information is gone and you never know which index belongs to which aspect.

I don't understand what this statement means. Are you referring to the order within ShapeLists as these are generally undefined unless sorted in some way.

[gumyr]

I strongly recommend that all new users go through all of the Introductory Examples (https://build123d.readthedocs.io/en/latest/introductory_examples.html) which will walk you through the build123d concepts from simple to complex - including using Locations to locate objects and selectors. Again, I strongly suggest that users don't just pick an index from a ShapeList but use one or more selectors to narrow down the list to just the desired object. Using a raw index is very brittle, potentially changing with some random code change. The ShapeLists are extensions of standard Python lists with indices of 0 and -1 indicating the first and last elements in the list respectively (the .first and .lastproperties are equivalent). If you have questions about how indexing lists work you can just google it as ShapeLIsts are effectively just fancy Python lists. The selector section of the docs (https://build123d.readthedocs.io/en/latest/key_concepts.html#selectors) provides more information including some of the build123d specific methods like sort_by, group_by, filter_by, and filter_by_position. One can sort or filter by Axis, length, radius, geometric type etc. all to help quickly identify the desired object. Using standard Python lambdas, custom sorting and filtering can quickly be created.

As for writing "Build123d Basics" book, there are quite a few things on my to-do list, I guess this is yet another.

[Paul8043]

That is exactly what I did, several times. I do not have any problems with python lists. All the examples I have tried do really work and they help to increase understanding of the concepts of Build123d. However if you try to modify the examples, because you want to encorporate some features of the examples into your own model under construction, some unexpected things happen. Attaching a workplane to a face (examples 18 to 22) is not so easy, these things need to be trained, and therefore I have ask for the book "Build123d Basics". readthedocs is well written, but some features need a more deeper explanation.

Understanding planes, just by reading the API-doc of the Classs Plane is a real challenge. You look onto this table (very weird) and then you try to catch the concept behind this table. You look onto it several times, but no neuron in your brain will fire. If you are at the beginning of the learning curve (as I am at the moment) this is an almost impossible task.

   ======= ====== ====== ======
    Name    x_dir  y_dir  z_dir
    ======= ====== ====== ======
    XY      +x     +y     +z
    YZ      +y     +z     +x
    ZX      +z     +x     +y
    XZ      +x     +z     -y
    YX      +y     +x     -z
    ZY      +z     +y     -x
    front   +x     +y     +z
    back    -x     +y     -z
    left    +z     +y     -x
    right   -z     +y     +x
    top     +x     -z     +y
    bottom  +x     +z     -y
    ======= ====== ====== ======

The only thing you can do, learn it by heart and hope that you can recognize the logic behind later on. Up to now I could not find out how this table should be interpreted? The attached workplane has x/y-coordinates and I simply want to know which real axis is behind x and which is behind y?

[gumyr]

I appreciate your feedback as a new user - it's very valuable as new users become experienced users and don't pay as much attention to the documentation.

If you find documentation that doesn't make sense to you, you could generate a GitHub issue for it or even better, fix the documentation and create a pull request to share your fix with everyone.

With respect to Planes, this table is describing how the local Plane that you're creating relates to the global coordinate system. For example:

>>> Plane.YZ
Plane(o=(0.00, 0.00, 0.00), x=(0.00, 1.00, 0.00), z=(1.00, 0.00, 0.00))

Here the local x_dir aligns with the global positive y axis ( x=(0.00, 1.00, 0.00)) while the plane normal or z_dir is aligned with the global positive x axis (z=(1.00, 0.00, 0.00)). A common misunderstanding is:

>>> Plane.XZ
Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, -1.00, 0.00))

where the normal aligns with the negative y axis as all of the build123d Planes use a Right Hand Rule based coordinate system.

This stuff is complex and there is a lot to learn so be patient with yourself.

[Paul8043]

The docu seems to be correct, but sometimes difficult to understand. The same applies for some interfaces. The 3 axes seem to be pari passu (are equal in every aspect). But this table is not symmetrical, and it seems that the y-axis is underprivileged, because it does not appear in the parameter-list. So, if I want to attach a X/Y-plane to a face, it is very weird that z_dir is part of the game. My expectation was just to define what x_dir and y_dir should be. This would be for me the natural interface (a solution without taking care for the z-axis).

In the meantime I have learnt more about this subject. There are 8 possibilities to attach the X/Y-workplane. The definition could be made with:
x_dir & y_dir
z_dir & x_dir
z_dir & y_dir
all 3 should be sufficient to define a unique attachment.

It looks very much that the z_dir should be same as the normal of the selected face. The problem is that the OCP-viewer does only show the face-area, but not the normal. The normal could point to the origin or to outside infinity. If I cannot see it, I cannot know it. To be honest I have no awareness where the normals point to (there are always 2 choices). It is some kind of implicit knowledge. Implicit things are the source of most trouble. Should be avoided completely. This makes understanding very difficult.

The guess from this evenning would be:

• z_dir should be same as the normal of the face
• x_dir is used to snap the x/y-cross to the desired orientation (4 choices)
• y_dir is a consequence of the previous 2

You can play twisted world, if you set z_dir to the inverse of the face-normal. All extrusion go to the wrong direction. If x_dir is not correct, then x and y exchange their role and/or the axes go to the wrong direction. The behavior is totally crazy.

One last thing:
In the OCP-viewer the axis-indicator shows the y-axis going to the rear. If I put a cube on the center (0,0,0), is the face belonging to y+ considered as back or front?

[gumyr]

You are correct that only two of the axes need be defined. x_dir and z_dir are used but that is somewhat arbitrary.

extrude depends on the provided direction (or the Plane a sketch was constructed on in Builder mode) not the Face normal. One can extrude at oblique angles to get skewed object. Non-planar Faces can also be extruded.

ocp_viewer shows Faces in "pink" when the surface with a positive normal is pointing at the camera and "grey" when pointing away, as follows:

[Paul8043]

@jrmobley & @gumyr

Congratulations, great job. The code is already integrated and available to me. It works as expected, the cut-type coloring works perfectly and also the reversal of the wire direction.

Again, thank you very much.

[jdegenstein]

Would it be possible to extend e.g. line_type and fill_type optionally with RGBA ? I am really impressed with how the new ExportSVG works by the way!

[jrmobley]

Do you have any thoughts on the exact syntax for the RGBA output? I'm seeing that rgb(255 255 255 / 50%) is the current standard, but rgb(255,255,255,0.5) is supported as a legacy format, as well as rgba as a legacy alias for rgb in both cases. Also, I have not had much success with Inkscape recognizing any of those formats when an alpha value is added. Inkscape recognizes the colors correctly when only RGB are present. When Inkscape saves and SVG with alpha, it doesn't use the fill or stroke attributes, but instead the inline style attribute with fill and fill-opacity CSS styles. I don't know how important Inkscape compatibility is. Firefox is fine with my output.

[jrmobley]

Ah, never mind. I found more documentation. I was using Firefox specific behavior. There are fill-opacity and stroke-opacity attributes that work for everybody.

[jdegenstein]

Sounds good, I found this stack overflow post while researching which was fairly helpful on this topic https://stackoverflow.com/questions/6042550/svg-fill-color-transparency-alpha

Let me know if you are still looking for input.

[jrmobley]

PR #573 has the changes.

[jrmobley]

Sorry, been away from this for a while. Good to hear that you are digging the exporter. Yes, I can add an RGBA option to the SVG colors.

[gumyr]

It would be great to use the Color class here to make things consistent. It supports color by name, RGBA and hex value.

[jrmobley]

Perfect. Will do.

[Paul8043]

@jrmobley Glad to have you back.

To add the alpha to colors is a good idea. I would prefer the format rgb(255,255,255,0.5). Unfortunately my router accepts only colors without alpha. Is the old format (rgb(255,255,255) without alpha) still provided? Or is there another way how this can be customized?

[jrmobley]

If you keep using it the way you have been, you should get the same output as always.
Any fully opaque Colors will produce the same output as before.
Opacity, when not == 1, is output with fill-opacity and stroke-opacity attributes. The four parameter versions of rgb() turned out to be non-standard, and so I did not use them.