Main Content

gzmodel

Assign and retrieve Gazebo model information

Since R2021a

    Description

    example

    List = gzmodel("list") returns and displays a list of model names List available in the Gazebo world.

    If you do not define the output argument, the model names are returned in the MATLAB® Command Window.

    [Links,Joints] = gzmodel("info",modelname) returns and displays a list of link names Links and joint names Joints of the specified Gazebo model modelname.

    If you do not define the output argument, the model info is returned in the MATLAB Command Window.

    [Status,Message] = gzmodel("set",modelname,Name,Value) assigns values to the model parameters using one or more name-value pair arguments for the specified Gazebo model modelname. The function returns the status of the value assignments Status and the message of their success and failure Message. For example, gzmodel("set","unit_box","Position",[2 2 0.5]) sets the position of the model unit_box.

    If you do not define the output argument, the status and message are returned in the MATLAB Command Window.

    [Output1,...,OutputN] = gzmodel("get",modelname,params) retrieves values of the model parameters using one or more parameter name, params, for the specified Gazebo model modelname. The function returns one or more outputs Output1,...,OutputN, corresponding to the specified parameter names.

    If you do not define the output argument, the model parameters are returned in the MATLAB Command Window.

    sdfString = gzmodel("importSDF",modelname) returns the Simulation Description Format (SDF) of the specified Gazebo model as a string.

    If you do not define the output argument, the SDF model description are returned in the MATLAB Command Window.

    Examples

    collapse all

    Set up a simulation between MATLAB and Gazebo, receive data from Gazebo, and send commands to Gazebo.

    Prerequisite

    Follow the instructions in Perform Co-Simulation Between Simulink and Gazebo to download the Linux virtual machine (VM) with Gazebo and set up multiSensorPluginTest.world.

    Configure and Perform Gazebo Co-Simulation

    Initialize connection settings and check connectivity with the Gazebo plugin running on 192.168.198.129 and port 14581.

    gzinit("192.168.198.129",14581)

    Assign and Retrieve Gazebo Model Information

    List the models available in the Gazebo world.

    modelList = gzmodel("list")
    modelList = 1×11 string
        "ground_plane"    "unit_box"    "camera0"    "camera1"    "depth_camera0"    "depth_camera1"    "imu0"    "imu1"    "hokuyo0"    "hokuyo1"    "velodyne"
    
    

    Assign values to the Position and SelfCollide parameters of the unit_box model.

    [status,message] = gzmodel("set","unit_box","Position",[2 2 0.5],"SelfCollide","on")
    status = 1×2 logical array
    
       1   1
    
    
    message = 1×2 string
        "Position parameter set successfully."    "SelfCollide parameter set successfully."
    
    

    Retrieve the values of the Position and SelfCollide parameters of the unit_box model.

    [position,selfcollide] = gzmodel("get","unit_box","Position","SelfCollide")
    position = 1×3
    
                             2                         2           0.4999999999951
    
    
    selfcollide = logical
       1
    
    

    Assign and Retrieve Gazebo Model Link Information

    List the links available in the unit_box model.

    linkList = gzlink("list","unit_box")
    linkList = 
    "link"
    

    Assign values to the link parameters Mass and Gravity of the link link in the unit_box model.

    [status,message] = gzlink("set","unit_box","link","Mass",2,"Gravity","off")
    status = 1×2 logical array
    
       1   1
    
    
    message = 1×2 string
        "Mass parameter set successfully."    "Gravity parameter set successfully."
    
    

    Retrieve the values of the link parameters Mass and Gravity of the link link in the unit_box model.

    [mass,gravity] = gzlink("get","unit_box","link","Mass","Gravity")
    mass = 
         2
    
    
    gravity = logical
       0
    
    

    Assign and Retrieve Gazebo Model Joint Information

    List the joints available in the unit_box model.

    jointList = gzjoint("list","unit_box")
    jointList = 
    "joint"
    

    Assign a value to the joint parameter Damping of the axis Axis0 for the joint joint in the unit_box model.

    [status,message] = gzjoint("set","unit_box","joint","Axis","0","Damping",0.25)
    status = logical
       1
    
    
    message = 
    "Damping parameter set successfully."
    

    Retrieve the value of the joint parameter Damping of the axis Axis0 for the joint joint in the unit_box model.

    damping = gzjoint("get","unit_box","joint","Axis0","Damping")
    damping = 
                          0.25
    
    

    Reset all Gazebo model configurations.

    gzworld("reset")

    Input Arguments

    collapse all

    Gazebo model name, specified as a string scalar or character vector.

    Data Types: char | string

    Gazebo model parameters, specified as a comma-separated list of string scalars or character vectors. Specify the list of parameters you want to retrieve the values, from this table.

    ParametersDescription
    "EnableWind"

    Get the wind parameter of the Gazebo model.

    "IsStatic"

    Get the IsStatic parameter of the Gazebo model.

    "Orientation"

    Get the orientation parameter of the Gazebo model.

    "Position"

    Get the position parameter of the Gazebo model.

    "SelfCollide"

    Get the SelfCollide parameter of the Gazebo model.

    Example: [position,selfcollide] = gzmodel("get","unit_box","Position","SelfCollide")

    Data Types: char | string

    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.

    Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

    Example: For example, gzmodel("set","unit_box","Position",[2 2 0.5]) sets the position of the model unit_box.

    Gazebo model wind parameter, specified as the comma-separated pair consisting of 'EnableWind' and either 'on' or 'off'.

    Example: [status,message] = gzmodel("set","unit_box","EnableWind","off");

    Data Types: char | string

    Gazebo model IsStatic parameter, specified as the comma-separated pair consisting of 'IsStatic' and either 'on' or 'off'.

    Example: [status,message] = gzmodel("set","unit_box","IsStatic","off");

    Data Types: char | string

    Gazebo model orientation parameter, specified as the comma-separated pair consisting of 'Orientation' and a four-element quaternion vector of the form [w x y z].

    Example: [status,message] = gzmodel("set","unit_box","Orientation",[1 0 0 0]);

    Data Types: single | double

    Gazebo model position parameter, specified as the comma-separated pair consisting of 'Position' and a three-element vector of the form [x y z] in meters.

    Example: [status,message] = gzmodel("set","unit_box","Position",[0 0 0]);

    Data Types: single | double

    Gazebo model SelfCollide parameter, specified as the comma-separated pair consisting of 'SelfCollide' and either 'on' or 'off'.

    Example: [status,message] = gzmodel("set","unit_box","SelfCollide","off");

    Data Types: char | string

    Output Arguments

    collapse all

    List of models, returned as a cell array of character vectors.

    List of links in the model, returned as a cell array of character vectors.

    List of joints in the model, returned as a cell array of character vectors.

    Status of the values assigned to the parameters, returned as a logical array.

    Success or failure message, returned as a string array.

    Values of specified parameters, returned as a logical or numeric vector based on the specified parameters. The following table shows the returned data type of parameter values.

    ParametersDescription
    "EnableWind"

    Gazebo model wind parameter, returns a logical scalar.

    "IsStatic"

    Gazebo model IsStatic parameter, returns a logical scalar.

    "Orientation"

    Gazebo model orientation parameter, returns a four-element quaternion vector of the form [w x y z].

    "Position"

    Gazebo model position parameter, returns a three-element vector of the form [x y z] in meters.

    "SelfCollide"

    Gazebo model SelfCollide parameter, returns a logical scalar.

    Limitations

    • gzmodel function not supported with MATLAB Compiler™.

    Version History

    Introduced in R2021a