createShape

Create geometry for basic primitives

Since R2022b

Syntax

createShape(actor,type)

createShape(actor,type,inputspec)

Description

createShape(actor,type) creates the actor actor in the shape defined by type.

createShape(actor,type,inputspec) provides additional details specified by inputspec for the shape specified by type.

Examples

Build Actor from 3D Graphic Primitives Using MATLAB

This example shows how to build an actor from a 3D graphic primitive using MATLAB®.

You can use the sim3d.World and sim3d.Actor objects to create a 3D environment with an actor. First, you create a 3D environment and an actor object. Next, you build the actor from 3D graphic primitives, including box, cylinder, plane, and sphere using the createShape function. Then, you add the actor to the world, transform the actor, and set a view in the scene. Finally, you view the actor in the Simulation 3D Viewer window.

To build an actor from a 3D graphic primitive using Simulink®, see Build Actor from 3D Graphic Primitives Using Simulink.

Create 3D Environment

Create a world object.

world = sim3d.World();

Create Actor

Instantiate an actor object named Cylinder. You can use any name for the actor.

actor = sim3d.Actor(ActorName='Cylinder');

Build a cylinder shape for the actor object and specify its size. Specify a color. Add the actor object to the world.

createShape(actor,'cylinder',[0.5 0.5 .75]);
actor.Color = [1 0 1];
add(world,actor);

Set Actor Transformation

Use the actor object translation, rotation, and scale properties to orient the actor relative to the world origin.

actor.Translation = [0 0 0];
actor.Rotation = [0 0 0];
actor.Scale = [1 1 1];

Set Viewer Window Point of View

If you do not create a viewport, then the default view is set and you can use the keyboard shortcuts and mouse controls to navigate in the Simulation 3D Viewer window.

For this example, use the createViewport function to create a viewport.

viewport = createViewport(world,Translation=[-4.5 0 1]);

Run Animation

Run a simulation set for 10 seconds with a sample time of 0.02 seconds.

sampletime = 0.02;
stoptime = 10;
run(world,sampletime,stoptime)

Delete World

Delete the world object.

delete(world)

Input Arguments

actor — Actor class where new geometry is created

sim3d.Actor object

Actor class where the new geometry is created, specified as a sim3d.Actor object.

type — Name of 3D graphic primitive

'arrow' | 'box' | 'cone' | 'cylinder' | 'checker' | 'icosphere' | 'plane' | 'prism' | 'pyramid' | 'revolution' | 'sphere' | 'surf' | 'terrain' | 'torus' | 'triad' | 'tube'

Name of 3D graphic primitive, specified as one of these values:

• 'arrow'

• 'box'

• 'cone'

• 'cylinder'

• 'checker'

• 'icosphere'

• 'plane'

• 'prism'

• 'pyramid'

• 'revolution'

• 'sphere'

• 'surf'

• 'terrain'

• 'torus'

• 'triad'

• 'tube'

inputspec — Optional parameters of each shape type

details of shape type

Optional parameters of each shape type, specified as details of the shape type.

The table lists the optional parameters for each shape type.

Type	Optional Parameters	Example
'arrow'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Segments – Number of line segments to form the curved surface. Value – Real positive scalar Default Value – 9 Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3	createShape(ActObj,'arrow', [2 4 2], 16, 2)
'box'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1)	createShape(ActObj,'box', [2 2 2])
'cone'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Segments – Number of line segments to form the curved surface. Value – Real positive scalar Default Value – 24 Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3	createShape(ActObj,'cone', [2 3 4], 12, 2)
'cylinder'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Segments – Number of line segments to form the curved surface. Value – Real positive scalar Default Value – 24 Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3	createShape(ActObj,'cylinder', [2 3 4], 12, 2)
'checker'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Segments – Number of checker board divisions in X and X directions. Value – Real positive (1,2) vector Default Value – (10,10) Color1 – Alternating color on the checker board. Consists of a vector of color RGB components: [red green blue]. Value – Real (1,3) vector Default Value – (0,0,0) and (1,1,1) Color2 – Alternating color on the checker board. Consists of a vector of color RGB components: [red green blue]. Value – Real (1,3) vector Default Value – (0,0,0) and (1,1,1)	createShape(ActObj,'checker', [4 4 1], [4 4], [1 0 0], [0 0 1])
'icosphere'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Subdivision – Number of subdivisions of the icosahedron. With this value, the number of triangles grows exponentially. For values greater than 5, simulation takes more time to load and can result in timeout errors. Value – Real positive integer Default Value – 1 Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3	createShape(ActObj,'icosphere', [3 3 3], 2, 3)
'plane'	Size – Size (x,y,z) of shape, in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3 BothSides – Whether plane is visible from both sides or is visible only from one side. Value – true or false Default Value – true Note Depending on the Axis value, the corresponding x,y, or z does not impact the size of the plane.	createShape(ActObj,'plane', [3 0 3], 2, true)
'prism'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Peak – Longitudinal position of the peak relative to the base, in m. Value – Real positive scalar Default Value – 0.5 Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3	createShape(ActObj,'prism', [2 2 2], 0.25, 2)
'pyramid'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3	createShape(ActObj,'pyramid', [3 3 3], 2)
'revolution'	ZX – C as a matrix of 2D points in the Z-X plane that can be rotated around the Z-axis. Value – Real positive (1,3) vector Segments – Number of line segments to form the curved surface. Value – Real positive scalar BeginCap – Whether planar cap should be generated at the top end of the revolved shape. Value – true or false Default Value – false EndCap – Whether planar cap should be generated at the bottom end of the revolved shape. Value – true or false Default Value – false	createShape(ActObj,'revolution', [1 1; 2 3; 5 2], 24, true, true)
'sphere'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Segments – Number of line segments to form the curved surface. Value – Real positive scalar Default Value – 24 Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3	createShape(ActObj,'sphere', [2 2 2], 16, 2)
'surf'	X – X-coordinates of a grid in X-Y plane, specified as a matrix the same size as Z, or as a vector with length n, where [m,n] = size(Z). Y – Y-coordinates of a grid in X-Y plane, specified as a matrix the same size as Z, or as a vector with length m, where [m,n] = size(Z). Z – Z-coordinates, specified as a matrix. Z must have at least two rows and two columns. Z specifies the height at each X-Y coordinate.	createShape(ActObj,'surf', [1 2 3; 1 2 3; 1 2 3], [1 1 1; 2 2 2; 3 3 3], [1 2 3; 4 5 6; 1 2 3])
'terrain'	Size – Size (x,y,z) of the terrain base plane, in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Height – Elevation map of the terrain, in A-by-B matrix. The terrain base plane is subdivided depending on the A and B values. Value – Real (m,n) vector Default Value – [0 0; 0 0] Axis – Axis to which the base plane is perpendicular. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3 PlanarNormals – Whether all the normals should be perpendicular to the terrain base plane. Value – true or false Default Value – false	createShape(ActObj,'terrain', [4 4 4], [1 0 1 0;1 0 1 0], 2, true);
'torus'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) InnerR – Ratio of inner to outer radii. Value – Real positive scalar Default Value – 0.5 Segments – Number of line segments to form the curved surface. Value – Real positive scalar Default Value – 24 Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3	createShape(ActObj,'torus', [4 4 4], 2, 16, 1)
'triad'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Segments – Number of line segments to form the curved surface. Value – Real positive scalar Default Value – 16 D – Diameter of the triad. Value – Real positive scalar Default Value – 0.1	createShape(ActObj,'triad', [2 1 2], 20, 0.2)
'tube'	Size – Size (x,y,z), in m. Value – Real positive (1,3) vector Default Value – (1,1,1) Bore – Ratio of inner to outer radii of the tube. Value – Real positive scalar Default Value – 0.5 Segments – Number of line segments to form the curved surface. Value – Real positive scalar Default Value – 24 Axis – Axis of the shape. Value – 1 for X-axis, 2 for Y-axis, 3 for Z-axis Default Value – 3	createShape(ActObj,'tube', [2 2 2], 0.75, 26, 1)

Version History

Introduced in R2022b