nodePositionRandom

Generate random node positions

Since R2026a

Syntax

[nodePosition,polygonShapeOut] = nodePositionRandom(boundaryShape,boundaryDimension)

[nodePosition,polygonShapeOut] = nodePositionRandom(boundaryShape,boundaryDimension,Name=Value)

[nodePosition,polygonShapeOut] = nodePositionRandom(polygonShapeIn)

[nodePosition,polygonShapeOut] = nodePositionRandom(polygonShapeIn,Name=Value)

[nodePosition,polygonShapeOut] = nodePositionRandom(polygonShapeIn,boundaryShape,boundaryDimension)

[nodePosition,polygonShapeOut] = nodePositionRandom(polygonShapeIn,boundaryShape,boundaryDimension,Name=Value)

Description

The nodePositionRandom function randomly generates node positions within a specified region. You can define this region using a boundary shape and dimensions, a given polygon, or the intersection of two boundaries. This function enables you distribute serving nodes, such as next generation NodeB (gNB), access points (AP), or Central nodes, across a broad area. At the same time, it restricts served nodes, such as user equipment (UE) nodes, Station nodes, or Peripheral nodes, to the intersection of coverage zones. For more information about how to simulate this scenario, see the Randomly Place Wireless Nodes in Polygon and Visualize Placement example.

Generate Random Node Positions within Specified Boundary Shape and Dimensions

[nodePosition,polygonShapeOut] = nodePositionRandom(boundaryShape,boundaryDimension) generates a single random position within the specified boundary shape and dimensions.

[nodePosition,polygonShapeOut] = nodePositionRandom(boundaryShape,boundaryDimension,Name=Value) specifies the node position configuration parameters using one or more optional name-value arguments.

Generate Random Node Positions within Specified Polygon

[nodePosition,polygonShapeOut] = nodePositionRandom(polygonShapeIn) generates a single random node position within the specified polygon polygonShapeIn.

[nodePosition,polygonShapeOut] = nodePositionRandom(polygonShapeIn,Name=Value) specifies the node position configuration parameters using one or more optional name-value arguments. Note that the Center name-value argument does not apply when you use this syntax.

Generate Random Node Positions within Boundary Intersections

[nodePosition,polygonShapeOut] = nodePositionRandom(polygonShapeIn,boundaryShape,boundaryDimension) specifies the parent boundary details polygonShapeIn. The function considers two boundaries, one from the parent boundary and another defined by the boundaryShape and boundaryDimension arguments, and generates a single random node position exclusively in the area where these two boundaries intersect. Note that the output argument polygonShapeOut is a polyshape object representing the intersection of the parent boundary polygonShapeIn and the boundary defined by boundaryShape and boundaryDimension.

[nodePosition,polygonShapeOut] = nodePositionRandom(polygonShapeIn,boundaryShape,boundaryDimension,Name=Value) specifies the node position configuration parameters using one or more optional name-value arguments. For example, ZCoordinate=3.5 sets the z-coordinate of all node positions to 3.5 meters.

Examples

Randomly Place Nodes and Visualize Placement

Generate and visualize the random placement of wireless nodes within a rectangular area. Using the nodePositionRandom function, you distribute ten nodes uniformly inside a 100-by-100 meter region. Then, a wirelessNetworkViewer object displays the resulting node positions.

Set the area dimensions and number of nodes.

areaLength = 100;           % Rectangle length (meters)
areaWidth = 100;            % Rectangle width (meters)
numNodes = 10;              % Number of random nodes

Generate random node positions in the rectangle.

[nodePositions,rectPoly] = nodePositionRandom( ...
    "rectangle",[areaLength areaWidth],NumNodes=numNodes);

View the positions using the wireless network viewer.

viewer = wirelessNetworkViewer(CanvasSize=[200 200]);
addNodes(viewer,nodePositions,Type="RandomNodePositions")

Show the rectangle boundary.

showBoundary(viewer, ...
    Position=[0 0 0], ...
    BoundaryShape="rectangle", ...
    Bounds=[areaLength areaWidth], ...
    Name="RectangleBoundary")

Remove the node position by uncommenting this line of code.

% removeNodes(viewer)

Hide the rectangle boundary by uncommenting this line of code.

% hideBoundary(viewer)

Randomly Place Wireless Nodes in Rectangle and in Overlapping Area with Circle

Use the nodePositionRandom function to randomly place two groups of wireless nodes: you distribute the first group within a 100-by-100 meter rectangle, and then place the second group within the intersection of that rectangle and a 20-meter radius circle centered at the first node of the first group.

Define the size of the rectangle, the number of nodes in each group, and the radius of the circle.

areaSize = [100 100];        % Rectangle size (meters)
numGroup1Nodes = 3;          % Number of nodes in the first group (rectangle)
circleRadius = 20;           % Circle radius (meters)
numGroup2Nodes = 10;         % Number of nodes in the second group (intersection)

Randomly distribute the first group of nodes within the 100-by-100 meter rectangle.

[group1Positions, parentBoundaryPolygon] = nodePositionRandom("rectangle",areaSize,NumNodes=numGroup1Nodes);

Randomly place the second group of nodes within the intersection of the rectangle and a 20-meter radius circle centered at the first node of group 1.

[group2Positions,intersectBoundaryPolygon] = nodePositionRandom( ...
    parentBoundaryPolygon,"circle",circleRadius, ...
    Center=group1Positions(1,:),NumNodes=numGroup2Nodes);

Create a wireless network viewer.

viewer = wirelessNetworkViewer;

Add the first group of nodes, from the rectangle, to the viewer.

addNodes(viewer,group1Positions,Type="Group1")

Add the second group of nodes, from the intersection of rectangle and circle, to the viewer.

addNodes(viewer,group2Positions,Type="Group2")

Show the rectangle boundary.

showBoundary(viewer, ...
    Position=[0 0 0], ...
    BoundaryShape="rectangle", ...
    Bounds=areaSize, ...
    Name="RectangleBoundary", ...
    Tag="RectangleTag")

Show the intersection circle boundary.

showBoundary(viewer, ...
    Position=[group1Positions(1,1), group1Positions(1,2), 0], ...
    BoundaryShape="circle", ...
    Bounds=circleRadius, ...
    Name="IntersectionCircle", ...
    Tag="CircleTag")

This approach applies to various wireless network scenarios:

• 5G Networks: Assign the first group of nodes as base stations ( gNBs) and the second group as user equipment ( UEs). Place UEs within the coverage area of a gNB, using constraints to create realistic deployments.

• WLAN (Wi-Fi) Networks: Use the first group for Access Points and the second group for Stations. Position Stations within both the building (rectangle) and the signal range (circle) of an Access Point.

• Bluetooth Networks: Set the first group as Central devices and the second group as Peripherals. Place Peripherals within the communication range of a Central device.

Randomly Place Wireless Nodes in Polygon and Visualize Placement

Generate random positions for wireless nodes inside polygon. Define the polygon with four vertices to create an irregular quadrilateral region. Use the nodePositionRandom function to distribute nodes uniformly within the polygon. Visualize and explore the resulting network deployment with wirelessNetworkViewer.

Define a quadrilateral polygon.

pgon = polyshape([0 0 1 3], [0 3 3 0]);

Generate random node positions within this polygon.

numNodes = 10; 
[nodePosition,polygonShapeOut] = nodePositionRandom(pgon,NumNodes=numNodes);

Visualize the node placements by using a wireless network viewer.

viewer = wirelessNetworkViewer(CanvasSize=[10 10]);
addNodes(viewer,nodePosition,Type="Node Positions")

Input Arguments

boundaryShape — Boundary shape

"rectangle" | "circle"

Boundary shape for node position generation, specified as "rectangle" or "circle".

boundaryDimension — Boundary dimensions for node position generation

numeric scalar | two-element numeric vector

Boundary dimensions for node position generation, specified as a numeric scalar or a two-element numeric vector. Whether you specify a scalar or a two-element vector depends on the value of the boundaryShape argument.

• When the value of the boundaryShape argument is "rectangle", specify the value of this argument as a vector of the form [l w], where l is the length and w is the width of the rectangle.

• When the value of the boundaryShape argument is "circle", specify the value of this argument as the radius of the circle, r.

The units are in meters.

Data Types: double | single

polygonShapeIn — Polygon-like shapes

polyshape object | N-element array of polyshape objects

Polygon-like shapes, specified as a polyshape object or an N-element array of polyshape objects.

Note that, if you also specify boundaryShape and boundaryDimension, polygonShapeIn must be a scalar polyshape object. If you do not specify boundaryShape and boundaryDimension, you can specify polygonShapeIn as a polyshape object or an N-element array of polyshape objects.

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: ZCoordinate=3.5 sets the z-coordinate for node positions to 3.5 meters.

Center — Center coordinates of boundary

[0 0] (default) | two-element vector | three-element vector | N-by-2 matrix | N-by-3 matrix

Center coordinates of the boundary, specified as a two-element vector, three-element vector, an N-by-2 matrix, or an N-by-3 matrix. Units are in meters.

When you specify this argument as a matrix, each row defines the center of a boundary area with dimensions boundaryDimension. Note that when you specify the Center name-value argument as an N-by-3 matrix, the function ignores the third column.

Note that this behavior is particularly useful in scenarios where you want to generate served nodes within a boundary centered around the serving node. For example, you can pass the position of a 5G base station, created with the nrGNB (5G Toolbox) object, as the center to the nodePositionRandom function. With this approach, you can generate user equipment node positions within a boundary centered on the base station. Wireless network simulations often represent node positions as 3-D Cartesian coordinates: [x, y, z]. By allowing the Center argument to accept a three-element vector, you can use these positions directly without extracting only [x, y]. For example, you can set Center = [50 50 10]. The function ignores the third value.

Data Types: double | single

NumNodes — Number of node positions to generate

1 (default) | positive integer

Number of node positions to generate, specified as a positive integer.

Data Types: double | single

ZCoordinate — z-coordinate of node positions

0 (default) | numeric scalar

z-coordinate of the node positions, specified as a numeric scalar. The units are in meters.

Data Types: double | single

Output Arguments

nodePosition — Generated node positions

three-element row vector | N-by-3 matrix

Generated node positions, returned as a three-element row vector or an N-by-3 matrix. N is the total number of generated positions within the boundary. The function determines the value of N based on these:

• If you specify boundaryShape and boundaryDimension, the function determines the value of N based on Center and NumNodes.

• If you do not specify boundaryShape and boundaryDimension, the function determines the value of N based on the number of polyshape objects and NumNodes.

Note that each row specifies the position of a node in Cartesian x-, y-, and z-coordinates. Units are in meters. The ith row contains the 3-D Cartesian coordinates for the ith node.

polygonShapeOut — Boundary information

polyshape object | N-element array of polyshape objects

Boundary information, returned as a polyshape object or an N-element array of polyshape objects.

• If you specify a single boundary or intersection, polygonShapeOut is a scalar polyshape object.

• If you specify N boundary regions, polygonShapeOut is an N-element array of polyshape objects.

Version History

Introduced in R2026a