Main Content

polarregion

Filled polar rectangle

Since R2024a

    Description

    polarregion(thetas,radii) creates a filled polar rectangle that is bounded by the angles in thetas and the radius values in radii in the current (polar) axes. To create one polar rectangle, specify thetas and radii as two-element vectors. To create multiple rectangles, specify two matrices of the same size.

    example

    polarregion(thetas,radii,Name=Value) specifies properties for the polar rectangle using one or more name-value arguments. If you create multiple rectangles, the property values apply to all of the rectangles. Specify the name-value arguments after all other inputs. For example, create a yellow polar rectangle using polarregion([0 pi],[0.25 1],FaceColor="yellow"). For a list of properties, see PolarRegion Properties.

    example

    polarregion(pax,___) specifies the target polar axes for the polar rectangle. Specify pax as the first argument in any of the previous syntaxes.

    example

    pr = polarregion(___) returns one or more PolarRegion objects. Use pr to set properties of the polar rectangles after creating them. For a list of properties, see PolarRegion Properties.

    example

    Examples

    collapse all

    Create a polar plot. Then add a polar rectangle between the angles 0 and pi/2 and the radii 0.5 and 0.8.

    % Create polar plot
    theta = 0:0.01:2*pi;
    rho = 2*sin(2*theta).*cos(2*theta);
    polarplot(theta,rho,LineWidth=1.5)
    
    % Create polar rectangle
    thetas = [0 pi/2];
    radii = [0.5 0.8];
    polarregion(thetas,radii)

    Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type line, polarregion.

    Change the theta-axis units to radians by setting the ThetaAxisUnits property.

    pax = gca;
    pax.ThetaAxisUnits = "radians";

    Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type line, polarregion.

    Create three filled polar rectangles by specifying the bounding angles and radii as 2-by-3 matrices. The columns of the matrices correspond to the different rectangles.

    thetas = [pi/6 4*pi/6 pi; 2*pi/6 5*pi/6 2*pi];
    radii = [0.5 0.5 0.6; 0.6 0.6 0.7];
    polarregion(thetas,radii)

    Figure contains an axes object with type polaraxes. The polaraxes object contains 3 objects of type polarregion.

    You can specify PolarRegion properties, such as face color and boundary line width and color, by specifying one or more name-value arguments when you call polarregion. Alternatively, you can set properties of the PolarRegion object after creating it.

    For example, create two green filled rectangles: one in the first (upper-right) quadrant and the other in the third (lower-left) quadrant. Specify an output argument to store the PolarRegion objects so that you can modify them later.

    thetas = [0 pi; pi/2 3*pi/2];
    radii = [0.5 0.8];
    pr = polarregion(thetas,radii,FaceColor="g");

    Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type polarregion.

    Change the color of the rectangle in the third quadrant to a shade of purple by specifying the FaceColor property as a hexadecimal color code. Then display thick boundary lines around the rectangle in the first quadrant by setting the EdgeColor and LineWidth properties:

    % Set color of rectangle in third quadrant
    pr(2).FaceColor = "#5500FF";
    
    % Set boundary color and line thickness in first quadrant
    pr(1).EdgeColor = "b";
    pr(1).LineWidth = 1.5;

    Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type polarregion.

    Plot a blue rose and a red rose.

    theta = linspace(0,2*pi,200);
    rho1 = 2*cos(3*theta);
    rho2 = 2*cos(3*theta+pi);
    
    % Blue rose
    rose1 = polarplot(theta,rho1,LineWidth=1.5);
    hold on
    
    % Red rose
    rose2 = polarplot(theta,rho2,LineWidth=1.5);

    Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type line.

    Create polar rectangles that highlight the tip of a petal in each rose.

    radii = [1.5 2];
    thetas1 = [7*pi/6 9*pi/6];
    pr1 = polarregion(thetas1,radii);
    
    thetas2 = [pi/6 3*pi/6];
    pr2 = polarregion(thetas2,radii);

    Figure contains an axes object with type polaraxes. The polaraxes object contains 4 objects of type line, polarregion.

    Match the color of each polar rectangle to the corresponding rose by setting the SeriesIndex property of the rectangle to the SeriesIndex property of the rose.

    pr1.SeriesIndex = rose1.SeriesIndex;
    pr2.SeriesIndex = rose2.SeriesIndex;

    Figure contains an axes object with type polaraxes. The polaraxes object contains 4 objects of type line, polarregion.

    To move a polar rectangle on top of a plot, set the Layer property of the PolarRegion object to "top". For example, plot a polar rose and add a polar rectangle. When you create the rectangle, specify a custom face color and a transparency value so that you can see that the rose is on top of the rectangle.

    % Plot polar rose
    t = 0:0.01:2*pi;
    rho = sin(2*t).*cos(2*t);
    polarplot(t,rho,LineWidth=1.5)
    
    % Add polar rectangle
    thetas = [0 pi];
    radii = [0.2 0.3];
    pr = polarregion(thetas,radii,FaceColor=[0.8 0.8 0.8],FaceAlpha=0.7);

    Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type line, polarregion.

    Move the rectangle on top of the rose by setting the Layer property to "top".

    pr.Layer = "top";

    Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type line, polarregion.

    To create filled polar rectangles in different polar axes within the same figure, create a tiled chart layout. In this case, create two axes that each contain a polar rectangle.

    Use the tiledlayout function to create a 1-by-2 tiled chart layout t. Use the polaraxes function to create each PolarAxes object. By default, both objects occupy the first tile. Move the second PolarAxes object to the second tile by setting the Layout.Tile property.

    t = tiledlayout(1,2);
    pax1 = polaraxes(t);
    pax2 = polaraxes(t);
    pax2.Layout.Tile = 2;

    Figure contains 2 axes objects. Polaraxes object 1 is empty. Polaraxes object 2 is empty.

    Create a red polar rectangle in the first polar axes, and create a green rectangle in the second polar axes. Specify the PolarAxes object that you want to plot into as the first argument when you call polarregion.

    thetas = [0 pi];
    radii = [0.2 0.6];
    polarregion(pax1,thetas,radii,FaceColor="r")
    polarregion(pax2,thetas,radii,FaceColor="g")

    Figure contains 2 axes objects. Polaraxes object 1 contains an object of type polarregion. Polaraxes object 2 contains an object of type polarregion.

    Input Arguments

    collapse all

    Bounding angles and radii, specified as a pair of two-element vectors or as a pair of 2-by-n or n-by-2 matrices, where n is the number of polar rectangles. Whether you specify vectors or matrices depends on the number of polar rectangles you create:

    • To create one filled rectangle, specify thetas and radii as two-element vectors.

    • To create n filled rectangles, specify thetas and radii as 2-by-n or n-by-2 matrices.

    • To create two filled rectangles, you can specify a 2-by-2 matrix and a two-element vector, or you can specify two 2-by-2 matrices. Each column of the matrices corresponds to a filled rectangle.

    Example: polarregion([0 pi/2],[0.5 1]) creates one polar rectangle.

    Example: polarregion([0 pi/4 pi; pi/6 pi/2 3*pi/2],[0.1 0.3 0.6; 0.2 0.4 0.7]) creates three polar rectangles.

    Example: polarregion([0 pi/4; pi/6 pi/2],[0.5 0.8]) creates two filled rectangles.

    If you specify an angle or radius as a NaN value, no rectangle appears for that value.

    Data Types: single | double

    Target axes for the filled region, specified as a PolarAxes object. Use this argument if you want to create the filled region in a specific PolarAxes object instead of the current axes.

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: polarregion([0 pi],[0.5 1],FaceColor="yellow") creates a yellow polar rectangle.

    Note

    The properties listed here are only a subset. For a complete list, see PolarRegion Properties.

    Fill color, specified as an RGB triplet, a hexadecimal color code, or a color name.

    For a custom color, specify an RGB triplet or a hexadecimal color code.

    • An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

    • A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

    Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

    Color NameShort NameRGB TripletHexadecimal Color CodeAppearance
    "red""r"[1 0 0]"#FF0000"

    Sample of the color red

    "green""g"[0 1 0]"#00FF00"

    Sample of the color green

    "blue""b"[0 0 1]"#0000FF"

    Sample of the color blue

    "cyan" "c"[0 1 1]"#00FFFF"

    Sample of the color cyan

    "magenta""m"[1 0 1]"#FF00FF"

    Sample of the color magenta

    "yellow""y"[1 1 0]"#FFFF00"

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

    "none"Not applicableNot applicableNot applicableNo color

    Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB® uses in many types of plots.

    RGB TripletHexadecimal Color CodeAppearance
    [0 0.4470 0.7410]"#0072BD"

    Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

    [0.8500 0.3250 0.0980]"#D95319"

    Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

    [0.9290 0.6940 0.1250]"#EDB120"

    Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

    [0.4940 0.1840 0.5560]"#7E2F8E"

    Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

    [0.4660 0.6740 0.1880]"#77AC30"

    Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

    [0.3010 0.7450 0.9330]"#4DBEEE"

    Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

    [0.6350 0.0780 0.1840]"#A2142F"

    Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

    Boundary line color, specified as an RGB triplet, a hexadecimal color code, or a color name.

    For a custom color, specify an RGB triplet or a hexadecimal color code.

    • An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

    • A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

    Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

    Color NameShort NameRGB TripletHexadecimal Color CodeAppearance
    "red""r"[1 0 0]"#FF0000"

    Sample of the color red

    "green""g"[0 1 0]"#00FF00"

    Sample of the color green

    "blue""b"[0 0 1]"#0000FF"

    Sample of the color blue

    "cyan" "c"[0 1 1]"#00FFFF"

    Sample of the color cyan

    "magenta""m"[1 0 1]"#FF00FF"

    Sample of the color magenta

    "yellow""y"[1 1 0]"#FFFF00"

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

    "none"Not applicableNot applicableNot applicableNo color

    Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

    RGB TripletHexadecimal Color CodeAppearance
    [0 0.4470 0.7410]"#0072BD"

    Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

    [0.8500 0.3250 0.0980]"#D95319"

    Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

    [0.9290 0.6940 0.1250]"#EDB120"

    Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

    [0.4940 0.1840 0.5560]"#7E2F8E"

    Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

    [0.4660 0.6740 0.1880]"#77AC30"

    Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

    [0.3010 0.7450 0.9330]"#4DBEEE"

    Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

    [0.6350 0.0780 0.1840]"#A2142F"

    Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

    Fill color transparency, specified as a scalar in the range [0,1]. A value of 1 is opaque and 0 is completely transparent. Values between 0 and 1 are partially transparent.

    Boundary line style, specified as one of the options listed in this table.

    Line StyleDescriptionResulting Line
    "-"Solid line

    Sample of solid line

    "--"Dashed line

    Sample of dashed line

    ":"Dotted line

    Sample of dotted line

    "-."Dash-dotted line

    Sample of dash-dotted line, with alternating dashes and dots

    "none"No lineNo line

    Version History

    Introduced in R2024a

    See Also

    Functions

    Properties