Main Content

createShape

Create geometry for basic primitives

Since R2022b

    Description

    example

    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

    collapse all

    This example shows how to build an actor from a 3D graphic primitive using either Simulink® or MATLAB®. You can use the createShape function to build an appearance for the actor using predefined 3D graphic primitives, including box, cylinder, plane, and sphere.

    Build Actor from 3D Graphic Primitive Using Simulink

    You can use Simulation 3D Actor block and Simulation 3D Scene Configuration block to create a virtual world with an actor. You can build the appearance of the actor from a 3D graphic primitive and set a view in the scene to view the actor in the Simulation 3D Viewer window.

    Open Model

    Open the Simulink model.

    open_system("CreateActorFrom3DGraphic");

    Simulink model with Simulation 3D Actor block named cylinder and Simulation 3D Scene Configuration block

    Explore Model Components

    The model includes a Simulation 3D Actor block and a Simulation 3D Scene Configuration block. The Simulation 3D Scene Configuration block implements a 3D simulation environment. Double-click the Simulation 3D Scene Configuration block to open the Block Parameters dialog box. Set a view in the scene with the Scene view parameter. You can also set a custom viewpoint with this parameter. You must include the configuration block when building Simulink models with Simulation 3D Actor blocks.

    Block parameter dialog box of Simulation 3D Scene Configuration block

    The Simulation 3D Actor block adds an actor to the virtual world. Double-click the Simulation 3D Actor block to open the Block Parameters dialog box. To create an actor before simulation starts, on the Main tab, set the Operation parameter to Create at setup. The block first creates an empty actor with the name specified in the Actor name parameter. You can use any name for the actor. Then, the block loads the source file, if any is present, and runs the Initialization script. For more details, see Operating Modes. The Initialization script builds a cylinder shape for the actor using the createShape function. Set the size and use the Properties of the actor object to set the color of the cylinder in the Initialization script text box. On the Transform tab, you can also set the Initial position, Initial rotation and Actor scale of the actor.

    The block parameter dialog box of the Simulation 3D Actor block shows parameters and the initialization script.

    Simulate Model

    Simulate the model and view the virtual world with cylinder shape actor in the Simulation 3D Viewer.

    sim("CreateActorFrom3DGraphic");

    Cylinder actor in the virtual world.

    Close Model

    Close the Simulink model.

    close_system("CreateActorFrom3DGraphic");

    Build Actor from 3D Graphic Primitive Using MATLAB

    You can use the sim3d.World and sim3d.Actor objects to create a virtual world with an actor. First, you create a virtual world and an actor object. Next, you build the actor from a 3D graphic 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.

    Create a world scene.

    world = sim3d.World();

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

    ActObj = 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(ActObj,'cylinder', [0.5, 0.5, .75]);
    ActObj.Color = [1, 0, 1];
    add(world,ActObj);

    Set Actor Transformation

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

    ActObj.Translation = [0 0 0];
    ActObj.Rotation = [0, 0, 0];
    ActObj.Scale = [1, 1, 1];

    Set Viewer Window Point of View

    If you do not create a viewport, then the point of view is set to 0, 0, 0, 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 with a single field, Main, that contains a sim3d.sensors.MainCamera object.

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

    Run Animation

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

    run(world,0.02,10)

    Cylinder actor in the virtual world.

    Delete World

    Delete the world object.

    delete(world)

    Input Arguments

    collapse all

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

    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'

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

    The table lists the optional parameters for each shape type.

    TypeOptional ParametersExample

    '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