V2 API - 2D Primitive Shapes

[z3dev]

Discussion about V2 API for 2D shapes.

Geometries (point / polygon based)

• polyline2 (?)
  • points [[x,y],[x,y]], ordered
  • open with no measurable area
• geom2
  • sides [[[x,y],[x,y]],...], unordered
  • closed with measurable area

Geometry Generation

• triangle ==> geom2
  • sides [1,1,1]
  • angles [60,60,60]
  • center [0,0]
  • start angle 0
• quadrangle ==> geom2
  • sides [1,1,1,1]
  • angles [90,90,90,90]
  • center [0,0]
  • start angle 0
• ellipse ==> geom2
  • radius [1,2]
  • center [0,0]
  • segments DEFAULT
  • start angle 0
  • end angle 360
• polygon ==> geom2
  • points [[x,y],...]

Shapes

• path2
  • transform (?)
  • curves
  • direction
• shape2
  • transform
  • geometry

API Declarations

• triangle
• quadrangle
• ellipse
• polygon
• path

API Aliases

• square
  • radius 1 => quadrangle [1,1,1,1) ...
• rectangle
  • radius [1,2] ==> quadrangle [1,2,1,2] ...
• circle
  • radius 1 ==> ellipse [1,1] ...

[z3dev]

There is also...

• roundedRectangle

Is this another shape?
Maybe a general roundedPolygon would be best.

[z3dev]

The SVG 2 basic shapes....

Mathematically, these shape elements are equivalent to a ‘path’ element that would construct the same shape. The basic shapes may be stroked, filled and used as clip paths.

10.2. The ‘rect’ element
10.3. The ‘circle’ element // WHY?
10.4. The ‘ellipse’ element
10.5. The ‘line’ element
10.6. The ‘polyline’ element
10.7. The ‘polygon’ element

SVG parameters...

• cx cy
• rx ry

[kaosat-dev]

Nice list !
A few notes:

• why quadrangle instead of rectangle (I saw the alias but do not quite get it)
• roundedRectangle: not so sure about that one, roundedPolygon does not make much more sense to me either (see below)
• I think we should take a close look at what maker.js is doing for paths, rounded shapes etc (for 2d shapes)
• all closed shapes are specialized versions of closed paths in a way :)

[z3dev]

I’m not even sure quadrangle is necessary. It’s just a more general form of a 4 sided polygon that allows angles other than 90 degrees.

We really have to decide what basic shapes to provide. Comparing the current API to other standards/applications should help.

@danmarshall may have a few suggestions about this, but I think maker.js is SVG based.

[z3dev]

Rounding of corners is really important but we might want to generalize the API. Instead of rounded* functions, we have a operation... would be a challenging function.

roundCorners

• options radius
• objects []

[kaosat-dev]

it would be nice, but generic operations to round corners is near impossible to do (or at least very very hard : ie topology): how do you decide WHICH corner to round etc ?

[danmarshall]

Great discussion guys! BTW Maker.js isn't SVG based, it is completely abstract from any format other than its own JSON schema :)

I would omit triangle and quadrangle and just go with polygon, with a series of points.

Are you still considering having the "point to point" API? Functions such as "lineTo", and "bezierTo" which you can use to create a shape.

To get rounded corners on any polygon, we can do some computation on a polyline, and apply fillets, similar to what Maker.js does: https://maker.js.org/docs/working-with-chains/#Chain%20fillet

[z3dev]

@danmarshall Thanks for joining... should be fun.

I adjusted the list, separating the ‘geometry’ objects out. FYI, segment is new, as that class does not exist today (the current lines are really unbounded never ending lines)

Path is one of the discussion points. I like this class as it has a set of arc functions to produce points. But it needs to be integrated better with line and polygon.

[z3dev]

DXF 2D Entities

• ARC
• CIRCLE
• ELLIPSE
• HATCH
• HELIX
• LINE
• LWPOLYLINE
• MLINE
• POLYLINE
• RAY
• SUN

[kaosat-dev]

I am a great fan of the 100% declarative way Maker.js uses for creating paths, bezier etc , I REALLY dislike the imperative "lineTo", and "bezierTo" :)

[z3dev]

I will take a look.

Wondering if polyline should be part of the API for storage. It seems to me that the new caching could use another API to make things more efficient. We want a superior 2D API as well as 3D.

[pentacular]

I think there are some additional requirements for paths.

(a) Directed traversal, noting circularity

Paths need to have direction, and it should be easy to find the next step in the path without transforming it into a graph.

So combination of { ordered sequence of points, circular } seems reasonable.
(If we don't note circularity then we will need to test for it for many operations.)

(b) Inside and outside edges.

Paths need to have a notional inside and outside edge (e.g., following the CCW convention, the right side of the path is outside, and the left side is inside).

This property needs to be kept for open paths as well as closed paths, so that things like toolpath routing can be accommodated.

(e.g., running a milling bit alongside a path so as to produce an edge on the path, likewise for laser cutting).

(c) Conversion to and from shape2 while preserving holes.

(d) Conversion of shape3 to shape2s to paths to shape2s to the original shape3 should also be supported.

Note that (c) is supported already by (a) and (b), but may require some additional care in shape2 to avoid the current vertex collision issue in getOutlinePaths().

Note that (d) precludes the use of arcs in paths, since they won't survive the round-trip.

This requires arc approximation by short path segments.

This results in three primitive forms -- path, shape2, shape3 -- from which all other shapes can be produced.

[z3dev]

These concerns have been addressed as part of V2, so closing this issue.