Path¶

class photonforge.Path(origin, width, offset=0, caps=(0, 0), scale_profile=True)¶

Planar path object.

Parameters:

origin – Path starting vertex.
width – Path width.
offset – Othogonal offset from the central path spine.
caps – Tuple of 2 values (for the initial and final path end caps). Each value represents the fraction of the width by which the path is extended. Each value can also be set to "round" for rounded caps.
scale_profile – Indicate whether the width and offset of this path should scale when the path is scaled.

Note

Arguments width and offset are values in the constructor, but can be an interpolation specification in all section builders (e.g., Path.segment()). The specification can be:

value: same as (value, "linear").
(value, "constant"): constant value over the whole section.
(to_value, "linear"): linear interpolation from the current value to to_value.
(from_value, to_value, "linear"): linear interpolation from from_value to to_value.
(to_value, "smooth"): smooth interpolation from the current value to to_value (uses a 3rd degree polynomial with zero derivatives at both endpoints).
(from_value, to_value, "smooth"): smooth interpolation from from_value to to_value.
(value_expression, derivative_expression): string expresssions evaluated along the path to get the width/offset value and its derivative, parametrized by the independet variable "u", which varies from 0 to 1 along the path. See the example below and the documentation on Expression for available operators.
expression: Expression with 1 parameter and at least 2 expressions. The last 2 expressions are used as position and derivative, respectively.

Example

>>> path = Path((0, 0), 0.5)
>>> path.segment((3, 0), ("0.5 + 0.5 * u^2", "u"))
>>> e = Expression(
...     "s", [("p", 3), "0.5 - 0.5 * s^p", "-0.5 * p * s^(p - 1)"]
... )
>>> path.segment((6, 0), e)

Methods

`arc`(initial_angle, final_angle[, radius, ...])	Add a circular, elliptical, or Euler arc to this path.
`area`()	Structure area.
`at`(u)	Return position, width, offset and gradient at a specific path location.
`bezier`(controls[, width, offset, relative])	Add a Bézier curve to this path.
`bounds`()	Calculate the structure bounds
`center`()	Get the central vertices of the path, accounting for offsets.
`copy`()	Create a copy of this structure.
`left_vertices`()	Get the left-side vertices of the path.
`length`()	Length of the path measured at the `Path.center()` vertices.
`mirror`([axis_endpoint, axis_origin])	Mirror this structure.
`parametric`(position[, gradient, width, ...])	Add a parametric curve to this path.
`right_vertices`()	Get the right-side vertices of the path.
`rotate`(rotation[, center])	Rotate this structure.
`s_bend`(endpoint[, euler_fraction, ...])	Add an S bend section to the path.
`scale`(scaling[, center])	Scale this structure.
`segment`(endpoint[, width, offset, ...])	Add a straight segment to this path.
`spine`()	Get the central vertices of the path, not taking offsets into account.
`to_polygon`()	Create a Polygon from this structure.
`transform`([translation, rotation, scaling, ...])	Apply a transformation to this structure: `self = translate(rotate(mirror(scale(self))))`
`translate`(translation)	Translate this structure.
`turn`(angle[, radius, euler_fraction, ...])	Add a circular or Euler turn to this path.

Attributes

`json`	Json representation of this path.
`size`	Number of path sections (read only).
`x_max`	Upper bound in the x axis.
`x_mid`	Bounding box center in the x axis.
`x_min`	Lower bound in the x axis.
`y_max`	Upper bound in the y axis.
`y_mid`	Bounding box center in the y axis.
`y_min`	Lower bound in the y axis.

arc(initial_angle, final_angle, radius=None, rotation=0, euler_fraction=0, endpoint=None, width=None, offset=None)¶

Add a circular, elliptical, or Euler arc to this path.

Parameters:

initial_angle – Starting angle of the arc section (in degrees).
final_angle – Ending angle of the arc section (in degrees).
radius – Arc radius. A sequence of 2 numbers can be passed to create an elliptical arc.
rotation – For elliptical arcs, the rotation of the main axis (in degrees).
euler_fraction – Fraction of the bend that is created using an Euler spiral (see note). It cannot be used for elliptical arcs.
endpoint – If set, force the endpoint location of the arc to these coordinates, compensating any numerical inaccuracies from the arc computation.
width – Path width over this section. It can be a number (linear interpolation from the current width over the whole section) or an interpolation specification (see the note in the class documentation).
offset – Path offset over this section. It can be a number (linear interpolation from the current offset over the whole section) or an interpolation specification (see the note in the class documentation).

Returns:

This path.

Example

>>> path = Path((0, 0), 0.5)
>>> path.arc(0, 90, 10, euler_fraction=0.5)
>>> path.arc(270, 90, (10, 6))

Note

The Euler bend fraction is implemented following the coefficient \(p\) in the work by Florian Vogelbacher et al., “Analysis of silicon nitride partial Euler waveguide bends,” Opt. Express 27, 31394-31406 (2019), doi: 10.1364/OE.27.031394.

area()¶

Structure area.

Returns:: Area of the structure.

at(u)¶

Return position, width, offset and gradient at a specific path location.

Parameters:: u – Parameter that defnes the location along the path, ranging from 0 to Path.size.
Returns:: Tuple with position, width, offset and gradient.

Example

>>> path = Path((0, 0), 0.5).segment([(10, 0), (10, 6)], 1)
>>> path.at(0.5)
(array([5., 0.]), 0.625, 0.0, array([10.,  0.]))
>>> path.at(path.size)
(array([10.,  6.]), 1.0, 0.0, array([0., 6.]))

bezier(controls, width=None, offset=None, relative=False)¶

Add a Bézier curve to this path.

Parameters:

controls – Bézier curve control points (at least 2).
width – Path width over this section. It can be a number (linear interpolation from the current width over the whole section) or an interpolation specification (see the note in the class documentation).
offset – Path offset over this section. It can be a number (linear interpolation from the current offset over the whole section) or an interpolation specification (see the note in the class documentation).
relative – If set, the controls are calculated relative to the current end point of the path.

Returns:

This path.

Example

>>> path = Path((0, 0), 0.5)
>>> path.bezier([(10, 0), (10, 5), (0, 10)])

bounds()¶

Calculate the structure bounds

Returns:: The lower-left and upper-right corners of the bounding box of the structure: ((min_x, min_y), (max_x, max_y)).

Example

>>> polygon = Polygon([(0, 1), (1, 2), (3, -1)])
>>> bounds = polygon.bounds()
>>> print(bounds)
((0.0, -1.0), (3.0, 2.0))

center()¶

Get the central vertices of the path, accounting for offsets.

Returns:: Array of coordinates.

copy()¶

Create a copy of this structure.

Returns:: New copy.

json¶: Json representation of this path.

left_vertices()¶

Get the left-side vertices of the path.

Returns:: Array of coordinates.

length()¶

Length of the path measured at the Path.center() vertices.

Returns:: Central path length.

mirror(axis_endpoint=(1, 0), axis_origin=(0, 0))¶

Mirror this structure.

Parameters:

axis_endpoint – Mirror axis endpoint.
axis_origin – Mirror axis origin.

Returns:

This object.

parametric(position, gradient=None, width=None, offset=None, relative=True)¶

Add a parametric curve to this path.

Parameters:

position – Tuple with 2 string expressions with the path position parametrized by a scalar "u", that varies from 0 to 1 along the path. Alternatively, an Expression with 1 parameter and at least 4 expressions can be used. The last 4 expressions are used, respectively, as horizontal and vertical positions and horizontal and vertical positon derivatives.
gradient – Tuple with 2 string expressions of values analogous to position to evaluate the path gradient. This parameter is required if position is a string tuple, and forbidden if it is an Expression.
width – Path width over this section. It can be a number (linear interpolation from the current width over the whole section) or an interpolation specification (see the note in the class documentation).
offset – Path offset over this section. It can be a number (linear interpolation from the current offset over the whole section) or an interpolation specification (see the note in the class documentation).
relative – If set, the position returned by the function is relative to the current end point of the path.

Returns:

This path.

Example

>>> path = Path((0, 0), 0.25)
>>> path.parametric(("-5 * u", "5 * u^2"), (-5, "10 * u"))
>>> spiral = Expression(
...     "u",
...     [
...         ("r0", 2),
...         ("dr", 2),
...         ("r", "r0 + dr * u"),
...         ("k", "1.5 * 2 * pi"),
...         ("c", "cos(k * u)"),
...         ("s", "sin(k * u)"),
...         ("x", "r * c - r0"),
...         ("y", "r * s"),
...         ("dx", "dr * c - r * k * s"),
...         ("dy", "dr * s + r * k * c"),
...     ],
... )
>>> path.parametric(spiral)

right_vertices()¶

Get the right-side vertices of the path.

Returns:: Array of coordinates.

rotate(rotation, center=(0, 0))¶

Rotate this structure.

Parameters:

rotation – Rotation angle in degrees.
center – Center of rotation.

Returns:

This object.

s_bend(endpoint, euler_fraction=0, direction=None, width=None, offset=None, relative=False)¶

Add an S bend section to the path.

Parameters:

endpoint – S bend endpoint.
euler_fraction – Fraction of the bend that is created using an Euler spiral (see Path.arc()).
direction – Direction of the S bend. If None, use current path direction.
width – Path width over this section. It can be a number (linear interpolation from the current width over the whole section) or an interpolation specification (see the note in the class documentation).
offset – Path offset over this section. It can be a number (linear interpolation from the current offset over the whole section) or an interpolation specification (see the note in the class documentation).
relative – If set, the end point is calculated relative to the current end point of the path.

Returns:

This path.

Example

>>> path = Path((0, 0), 0.5)
>>> path.s_bend((-6, 1), direction=(-1, 0))
>>> path.s_bend((-12, -1))

scale(scaling, center=(0, 0))¶

Scale this structure.

Parameters:

scaling – Magnification factor.
center – Center of scaling.

Returns:

This object.

segment(endpoint, width=None, offset=None, join_limit=-1.0, relative=False)¶

Add a straight segment to this path.

Parameters:

endpoint – Segment end point or list of vertices to create multiple segments at once.
join_limit – If the join between segments would create an intersection point beyond this limit (as a fraction of the local width), the join is beveled. A negative value disables beveling. This value can also be set to “round” to create rounded joins.
width – Path width over this section. It can be a number (linear interpolation from the current width over the whole section) or an interpolation specification (see the note in the class documentation).
offset – Path offset over this section. It can be a number (linear interpolation from the current offset over the whole section) or an interpolation specification (see the note in the class documentation).
relative – If set, the end point is calculated relative to the current end point of the path.

Returns:

This path.

size¶: Number of path sections (read only).

spine()¶

Get the central vertices of the path, not taking offsets into account.

Returns:: Array of coordinates.

to_polygon()¶

Create a Polygon from this structure.

Returns:: New polygon instance.

Examples

>>> rectangle = Rectangle((0, 0), (2, 1), rotation=45)
>>> polygon = rectangle.to_polygon()

>>> circle = Circle(5, (0, 0), inner_radius=3)
>>> polygon = circle.to_polygon()

>>> path = Path((0, 0), 0.5).s_bend((10, 2))
>>> polygon = path.to_polygon()

transform(translation=(0, 0), rotation=0, scaling=1, x_reflection=False)¶

Apply a transformation to this structure: self = translate(rotate(mirror(scale(self))))

Parameters:

translation – Coordinate pair used as a translation vector.
rotation – Rotation angle in degrees.
scaling – Magnification factor.
x_reflection – Mirror across the horizontal axis.

Returns:

This object.

translate(translation)¶

Translate this structure.

Parameters:: translation – Coordinate pair used as a translation vector.
Returns:: This object.

turn(angle, radius=None, euler_fraction=0.0, endpoint=None, width=None, offset=None)¶

Add a circular or Euler turn to this path.

Parameters:

angle – Turning angle (in degrees). Positive (negative) values make a clockwise (counter-clockwise) turn.
radius – Turning radius.
euler_fraction – Fraction of the bend that is created using an Euler spiral (see Path.arc()).
endpoint – If set, force the endpoint location of the turn to these coordinates, compensating any numerical inaccuracies from the turn computation.
width – Path width over this section. It can be a number (linear interpolation from the current width over the whole section) or an interpolation specification (see the note in the class documentation).
offset – Path offset over this section. It can be a number (linear interpolation from the current offset over the whole section) or an interpolation specification (see the note in the class documentation).

Returns:

This path.

x_max¶: Upper bound in the x axis.

x_mid¶: Bounding box center in the x axis.

x_min¶: Lower bound in the x axis.

y_max¶: Upper bound in the y axis.

y_mid¶: Bounding box center in the y axis.

y_min¶: Lower bound in the y axis.