polygonSweep

Generate path for sweep tool to cover polygon

Since R2026a

collapse all in page

    Syntax

    sweepPath = polygonSweep(poly)
    sweepPath = polygonSweep(poly,options)
    [___,solnInfo] = polygonSweep(___)

    Description

    The polygonSweep function generates a path for a sweep tool to follow to cover a polygon. For concave polygons, use the polygonMonotonicity and plotMonotonicity functions to identify and visualize the valid sweep angle intervals of the polygon.

    This figure shows an example of path generated for a concave polygon along the sweep direction, defined by a sweep angle of 0 degrees. For more information about identifying valid sweep angles, see the Monotonicity section of the polygonMonotonicity function. Note that the sweep angle refers to the angle of the sweep direction, not the lines of the sweep path.

    Sweep path generated for a concave polygon using a left-to-right sweep direction. The positive sweep line direction is from down to up.

    sweepPath = polygonSweep(poly) generates a sweep path using default sweep options.

    sweepPath = polygonSweep(poly,options) specifies sweep options.

    example

    [___,solnInfo] = polygonSweep(___) returns additional information about the sweep path solution using any combination of input arguments from previous syntaxes..

    Examples

    collapse all

    Open Live Script

    Define the geometry of a polygon as a polyshape object.

    poly = polyshape([0 0 1.5 3 3 1.875 1.5 1.1250 0],[0 2 1.5 2 0 0 0.5 0 0]);

    Check if any regions of the polygon are monotonic, and return the monotonic angle intervals for those regions.

    [isMono,intervals] = polygonMonotonicity(poly);

    Plot the monotonic intervals of the polygon.

    hVis = plotMonotonicity(poly);
axis equal tight
title(["Polygon and Corresponding","Monotonic Intervals"])
legend("Polygon","Monotonic Intervals",Location="northeastoutside")

    Figure contains an axes object. The axes object with title Polygon and Corresponding Monotonic Intervals contains 3 objects of type patch, polygon. These objects represent Polygon, Monotonic Intervals.

    You can use these monotonic intervals to plan sweep paths. Sweeping in a monotonic interval ensures that you can fully sweep the corresponding region of a polygon in one direction, without needing to backtrack.

    Store three sweep angles from within the first monotonic angle interval.

    sweepAngles = [intervals(1,1) mean(intervals(1,:)) intervals(1,2)] - pi;

    Define the geometry of the sweep tool. In this case, assume the tool is shaped like a regular pentagon.

    tool = nsidedpoly(5,Radius=0.1);

    Set up three subplots, for showing the sweep paths along the selected sweep angles.

    t = tiledlayout(1,3,Padding="compact",TileSpacing="compact");

    Generate and plot a sweep path for each of the stored sweep angles. Plot the sweep direction arrow and sweep line direction arrow to show their relationships to the sweep angle and path.

    for i = 1:3
opts = polysweepoptsbous(SweepAngle=sweepAngles(i),BoundaryBehavior="inset",SweepToolGeometry=tool);
path = polygonSweep(poly,opts);

nexttile

hVis = plotMonotonicity(poly);

hold on
axis equal tight

% Plot the swept path
pathHandle = plot(path(:,1),path(:,2));

% Plot the sweep direction arrow and sweep line direction arrows to
% show their relationships to the sweep angle and path.
sweepLineDirHandle = exampleHelperHighlightInterval(hVis,sweepAngles(i)+pi/2);
sweepDirHandle = exampleHelperPlotSweepDirection(poly,sweepAngles(i));

% Add a title to the current tile
title("Sweep Angle " + num2str(rad2deg(sweepAngles(i)),"%.1f") + "°");

hold off
end

handles = [hVis.MonotoneIntervals.Children(1), ...
           pathHandle, ...
           sweepDirHandle, ...
           sweepLineDirHandle];

legend(handles,{"Monotonic Interval","Sweep Path","Sweep Direction","Sweep Line Direction"},Location="southoutside",Orientation="vertical");

    Figure contains 3 axes objects. Axes object 1 with title Sweep Angle -36.9° contains 6 objects of type patch, polygon, line, quiver. Axes object 2 with title Sweep Angle 0.0° contains 6 objects of type patch, polygon, line, quiver. Axes object 3 with title Sweep Angle 36.9° contains 6 objects of type patch, polygon, line, quiver. These objects represent Sweep Path, Sweep Line Direction, Sweep Direction.

    Input Arguments

    collapse all

    Polygon to sweep, specified as a polyshape object.

    Note

    If the desired polygon contains holes, you must use the polygonDecomposition function to break the polygon into smaller convex polygons first. Otherwise, the polygon is not monotonic, meaning it is not possible to sweep the polygon with only one direction.

    Example: polyshape([0 0 1 1],[1 0 0 1]) creates a solid square defined by the four points (0, 1), (0, 0), (1, 0), and (1, 1).

    Sweep options, specified as a polysweepoptsbous object.

    Example: polysweepoptsbous(SweepAngle=pi/2)

    Output Arguments

    collapse all

    Sweep path, returned as an N-by-3 matrix. Each row is an SE(2) pose in the form [x y theta]. N is the total number of poses in the sweep path.

    Note

    The sweep path output includes direct transitions between sweep line endpoints, which are not constrained by the boundaries of the polygon. These segments are not intended for in-region coverage, but rather to reposition the tool for the next sweep line. If the transitions must respect the polygon boundaries, you can use path planners to create paths between the sweep-line end points.

    Sweep path solution information, returned as a structure with the field SolutionStatus containing these fields.

    • IsSweepable — Indicates whether the sweep path could be successfully generate, returned as either 1 (true) or 0 false).

    • SweepAngle — Sweep angle used for the sweep path, returned as a numeric scalar in the range [0, 2π), in radians. When you specify the SweepAngle property of options as NaN, the value of this field is a sweep angle that the polygonSweep function determined. Otherwise the value of this field is the same as the value of the SweepAngle property of options.

    Extended Capabilities

    expand all

    C/C++ Code Generation
    Generate C and C++ code using MATLAB® Coder™.

    Version History

    Introduced in R2026a

    See Also

    | | |