Ziro Studio API

Learn about all the Ziro Studio specific Python classes and methods

3D Shapes (with Physics)

3D Shape Objects

Ball(x=0, y=0, z=0, radius=1, mass=1, friction=1, cor=1, color='white') Returns a Ball with center at (x, y, z) with a specified radius, mass, friction, coefficient of restitution (bounce), and color.

Box(x=0, y=0, z=0, width=1, length=1, height=1, xr=1, yr=0, zr=0, rot=0, mass=1, friction=1, cor=0.5, color='white') Returns a Box with center at (x, y, z), with orientation specified by a (xr, yr, zr) vector and rot (in degrees) specifying how much to rotate around that vector. The block will have specified width, length, height, mass, friction, coefficient of restitution (bounce), and color.

Cone(x=0, y=0, z=0, radius=1, height=0, xr=1, yr=0, zr=0, rot=0, mass=1, friction=1, cor=0.5, color='white') Returns a Cone with center at (x, y, z), with orientation specified by a (xr, yr, zr) vector and rot (in degrees) specifying how much to rotate around that vector. The cone will have specified radius, height, mass, friction, coefficient of restitution (bounce), and color. Cylinder(x=0, y=0, z=0, radius=1, height=0, xr=1, yr=0, zr=0, rot=0, mass=1, friction=1, cor=0.5, color='white') Returns a Cylinder with center at (x, y, z), with orientation specified by a (xr, yr, zr) vector and rot (in degrees) specifying how much to rotate around that vector. The cylinder will have the specified radius, height, mass, friction, coefficient of restitution (bounce), and color.

Rope(x=0, y=0, z=0, numsegs=1, length=1, mass=1, color='tan') - (Pre-aLpha feature) Creates a rope object with a position of (x, y, z), and a number of segments, length, mass, and color all specified in the parameters.

Ground(x=0, y=0, z=0, width=1500, length=1, height=1500, xr=1, yr=0, zr=0, rot=0, mass=0, friction=2, cor=0.5) Creates a new ground object when initializing. Ground is created in Studio by default.

Friction can take values between 0 to 1. If it is 1 then the object does not move. Bounciness also takes values between 0 (no bounce) and 1 (perfect bounce with no loss of energy).

if an object has a mass of zero, it is treated as a static object

3D Shape Forces and Motion

.set_velocity(x, y, z) Sets the velocity of the object to the vector (x, y, z).

.apply_force(x, y, z) Applies a force vector (x, y, z) to the object in Newtons. This applies the force at the center of the object continuously over time.

you can apply a force of zero to stop applying force at any time.

.apply_torque(x, y, z) Applies a torque (rotational force) vector (x, y, z) to the object in Newton-meters. This applies the torque at the center of the object continuously over time.

you can apply a torque along with the force, if you want to apply force at a point away from the center of the object.

.apply_impulse(x, y, z) Applies an impulse vector (x, y, z) to the object. This applies the force at the center of the object one time at the instant the function is called.

.apply_torque_impulse(x, y, z) Applies a rotational impulse vector (x, y, z) to the object. This applies the torque at the center of the object one time at the instant the function is called.

All the parameters in these functions are in the global coordinate system.

3D Shape Manipulation

.set_position(x, y, z) Sets the position of the object to the coordinates x, y, z.

.set_orientation(xr, yr, zr, rot) Sets the orientation of the object specified by a (xr, yr, zr) vector and rot (in degrees).

.scale(x, y, z) Scales the object by the factor of x, y, and z along the x, y, z axis respectively in the local coordinate system of the object.

.set_color(color='white') Changes the color of the object.

.set_texture_image(url='') Sets the texture of the object to the specified image.

.remove() Removes the object from the scene.

Users can create non-physics-based 3D animations by setting mass of the shapes to zero, and using set_position and set_orientation functions followed by sleep function.

3D Shape Sensors

.get_position() Returns position of the object as a tuple (x, y, z).

.get_velocity() Returns velocity vector of the object as a tuple (x, y, z).

.get_orientation() Returns orientation of the object as a tuple (xr, yr, zr, rot).

.get_angular_velocity() Returns angular velocity vector of the object as a tuple (x, y, z).

.get_force(obj2) Returns the force between the object and a second object obj2.

3D Shape Tracking/Graphing

.set_camera_track() Sets the camera to track the position of the object.

create_custom_graph(title, x_label, y_label, x_data, y_data) This global function creates a custom graph with the specified title, x axis label, y axis label, x dataset, and y dataset(s).

.start_graph(graph_type="position") Start graphing either position or velocity specified by graph_type over time for an object.

.stop_graph(graph_type="velocity") Stop graphing either position or velocity specified by graph_type.

.download_graph(graph_type='position') Download object's graph to a .csv file specified by graph_type "position" or "velocity".

.set_pen_down() Puts the virtual pen down onto the canvas to start drawing the shape path.

.set_pen_up() Lifts the virtual pen up from the canvas to stop drawing the shape path.

.set_pen_color('color') Changes the color of the virtual pen. The color can be specified in the format 'color' or 'rgb (R, G, B)'.

.set_pen_thickness(thickness) Changes the thickness of the virtual pen. The thickness is 3 by default.

3D Shape Constraints

Hinge(obj1, obj2, x1=0, y1=0, z1=0, x2=0, y2=0, z2=0, rx1=0, ry1=0, rz1=0, rx2=0, ry2=0, rz2=0, velocity=0, motor_impulse=0) Returns Returns a hinge constraint between two objects specified by obj1 and obj2. (x1, y1, z1) is the pivot point in the local coordinate system of obj1, and (x2, y2, z2) is the pivot point for obj2. (rx1, ry1, rz1) is the axis of rotation in reference to obj1, and (ry1, ry2, rz2) is the axis of rotation in reference to obj2. It constrains all three translational degrees of freedom and allows only one rotational movement around the axis rotation given in the parameters. For more information on degrees of freedom, please see the note below.

P2P(obj1, obj2, x1=0, y1=0, z1=0, x2=0, y2=0, z2=0) Returns a Point-to-Point constraint (ball and socket joint) between two objects specified by obj1 and obj2. (x1, y1, z1) is the pivot point in the local coordinate system of obj1, and (x2, y2, z2) is the pivot point for obj2. It keeps the distance between obj1 and obj2 same so that obj2 moves with obj1, while they can rotate freely in all directions.

Fixed(obj1, obj2) Returns a fixed constraint object that removes all six degrees of freedom between obj1 and obj2.

There are six possible degrees of freedom for any point in total. Three translational degrees of freedom, allowing linear movements in x, y, and z directions, and three rotational degrees of freedom, allowing rotation around x, y, and z directions. Constraints are a way to limit one or more of these degrees of freedom to restrict the corresponding linear or rotational movements.

2D Shapes

2D Shape Objects

Circle(x=0, y=0, z=1, radius=1, theta = 360, xr=1, yr=0, zr=0, rot=0, color='white', fill='true') Returns a circle with center at (x, y, z) with orientation specified by a (xr, yr, zr) vector and rot (in degrees), with a specified radius, sector angle & color. (Orientation is useful if the Circle has an image texture.)

Rectangle(x=0, y=0, z=0, width=1, height=1, xr=1, yr=0, zr=0, rot=0, color='white', fill='true') Returns a rectangle with center at (x, y, z) with orientation specified by a (xr, yr, zr) vector and rot (in degrees), with a specified width, height, and color.

Polygon(x=0, y=0, z=0, sideLength=1, segments=3, xr=1, yr=0, zr=0, rot=0, color='white', fill='true') Returns a regular polygon of given number of segments with center at (x, y, z) with orientation specified by a (xr, yr, zr) vector and rot (in degrees), with a specified size and color.

Triangle(x1=0, y1=0, z1=0, x2=0, y2=1, z2=0, x3=1, y3, = 0, z3=0, xr=1, yr=0, zr=0, rot=0, color='white', fill='true') Returns a Triangle with three specified vertices, orientation specified by a (xr, yr, zr) vector and rot (in degrees), and color.

Line(x1=0, y1=0, z1=0, x2=1, y2=0, z2=0, xr=1, yr=0, zr=0, rot=0, color='white') Returns a line with two specified vertices, orientation specified by a (xr, yr, zr) vector and rot (in degrees), and color.

There is no way to control the width of a Line object. We recommend using a Rectangle object as a line if you would like to control the width.

2D shapes are not subjected to Physics. They are used strictly for graphics purposes.

2D Shape Manipulation

.set_position(x, y, z) Sets the position of the object to the coordinates x, y, z.

.set_orientation(xr, yr, zr, rot) Sets the orientation of the object specified by a (xr, yr, zr) vector and rot (in degrees).

.set_color(color='white') Changes the color of the object.

set_texture_image(url='') Sets the texture of the object to the specified image.

.remove() Removes the object from the scene.

For Line, the set_orientation function uses the first vertice as the origin (pivot point)

Users can create 2D animations by using set_position and set_orientation functions, followed by sleep function

2D Shape Sensors

.get_position() Returns the position of the object as a tuple (x, y, z).

.get_orientation() Returns the orientation of the object as a tuple (xr, yr, zr, rot).

3D Text

3D Text Object

Text3D(x=0, y=0, z=0, size=1, height=0.1, xr=0, yr=0, zr=0, rot=0, color='white', r=None, g=None, b=None, text = '') Returns a 3D Text object with center at (x, y, z) with orientation specified by a (xr, yr, zr) vector and rot (in degrees), with a specified text string, size, height, and color.

3D text is not subjected to Physics. It is used strictly for graphics purposes.

3D Text Manipulation

.set_text(text) Sets the text string of the object

.set_size(size) Sets the size of the object

.set_height(height) Sets the height of the object

.set_position(x, y, z) Sets the position of the object to the coordinates x, y, z.

.set_orientation(xr, yr, zr, rot) Sets the orientation of the object specified by a (xr, yr, zr) vector and rot (in degrees).

.set_color(color='white') Changes the color of the object.

.remove() Removes the object from the scene.

Users can create 3D text animations by using set_position and set_orientation functions, followed by sleep function.

3D Text Sensors

.get_position() Returns the position of the object as a tuple (x, y, z).

.get_orientation() Returns the orientation of the object as a tuple (xr, yr, zr, rot).

Groups

Group Object

Group(x = 0, y = 0, z = 0, xr=0, yr=0, zr=0, rot=0, objects = []) Returns a group of a given list of graphics objects with specified origin at (x, y, z) and orientation specified by a (xr, yr, zr) vector and rot (in degrees).

Group functionality works only on static/graphics objects. If you want to add 3D shapes to a group, please set their mass to zero. You can add graphics-only objects such as 2D shapes and 3D text or other group objects to a group.

Group Manipulation

.add_object(item) Add an object to the group

.remove_object(item) Remove an object from the group

.set_position(x, y, z) Sets the position of the group to the coordinates x, y, z.

.set_orientation(xr, yr, zr, rot) Sets the orientation of the group specified by a (xr, yr, zr) vector and rot (in degrees).

.move(x, y, z) Move the group by x, y, z from the current position

.remove() Removes the group from the scene.

The remove_object function only removes an object from the group. It doesn't remove the object from the scene. Also when an object is removed from the group its orientation is reset to its original value used at its creation.

Users can animate a group by using set_position and set_orientation functions, followed by sleep function.

Group Sensors

.get_objects() Returns the list of objects in the group

.get_position() Returns the position of the group as a tuple (x, y, z).

.get_orientation() Returns the orientation of the group as a tuple (xr, yr, zr, rot).

Virtual Robot

Robot Object

Robot(x=0, y=0, z=1, xr=0, yr=0, zr=1, rot=0, robot_color=None, wheel_color=None) Creates a robot at the specified position and with the given orientation and colors.

Robot Motion

.move_forward(distance, speed=100) Moves the virtual robot forward by the specified maximum speed.

.move_backward(distance, speed=100) Moves the virtual robot backward by the specified maximum speed.

.turn_left(angle, speed=100) Turns the virtual robot left by the specified angle (in degrees) at a specified maximum speed.

.turn_right(angle, speed=100) Turns the virtual robot right by the specified angle (in degrees) at a specified maximum speed.

The above precise movement functions run until the robot reaches the desired position or orientation. No need to use sleep function (defined later) to allow time for the robot to move.

You can also set speed values using the methods below if you don't want to use the pre-made distance movement functions.

.set_forward_speed(speed) Sets the forward speed of the virtual robot.

.set_turn_speed(speed) Sets the angular (turning) speed of the virtual robot.

Make sure you follow these advanced motion commands with sleep commands to indicate how long the virtual robot should move. Otherwise, it will not move!

The maximum and minimum allowed values are 300 and -300, respectively. You can use negative speeds to move backward and to turn left.

Robot Graphics

.set_pen_down() Puts the virtual pen down onto the canvas.

.set_pen_up() Lifts the virtual pen up from the canvas.

.set_pen_color('color') Changes the color of the virtual pen. The color can be specified in the format 'color' or 'rgb (R, G, B)'.

.set_pen_thickness(thickness) Changes the thickness of the virtual pen. The thickness is 3 by default.

.set_robot_color('color') Changes the color of the virtual robot.

.set_wheel_color('color') Changes the wheel color of the virtual robot.

.set_camera_track() Sets the camera to track the virtual robot.

Robot Sensors

.get_x_position() Returns the x position of the robot on the grid.

.get_y_position() Returns the y position of the robot on the grid.

.get_forward_speed() Returns the forward speed of the robot (positive if forwards, negative if backwards).

.get_angle() Returns the angle of the robot.

.get_turn_speed() Returns the turn speed of the robot (positive if right, negative if left).

.get_distance_to_object() Returns the distance to the nearest object directly in front of the robot. Returns 100 if no object is in sight.

.get_nearest_color() Returns the color of the nearest object in the form #hexcode (e.g. #ff00cc). Returns #null if there is no nearest object.

Robot Object Manipulation

.pick_nearest_object() Pick up the nearest object to the robot which has a mass greater than 0. The robot does not display the picked objects until it deposits them.

.deposit_objects(color_str='any', num_objects=-1) Deposit objects meeting the color criterion (as hex or 'any'). Deposit up to num_objects together, where -1, the default, indicates that all objects meeting the color criterion should be deposited. The objects are deposited in front of the robot.

Sound Commands (Coming Soon)

create_sound(waveform = 'sine', frequency = 440, length = 1) Plays a sound with a specified waveform (sine, square, triangle, or sawtooth), beep of frequency in Hz, and for length of time in seconds

play_sound(url = 'url', length = 1) Plays a sound file located at the specified url for given length of time in seconds

Camera Commands

set_camera_position(x=0, y=10, z=-10) Set the position of the camera to coordinates (x, y, z).

set_camera_look_at(x=0, y=0, z=0) Set the orientation of the camera to look at point (x, y, z).

Environment Commands

env_set_gravity(g) Set the gravitational acceleration in your environment to a specified value. By default, the gravity is the same as on Earth (9.81 m/s^2).

env_set_sky_color('color_str') Set the color of the sky.

env_set_ground_color('color_str') Set the color of the ground.

Miscellaneous Commands

sleep(time) Waits for time seconds while the simulation runs before letting the rest of the code run.

print("message") Writes the message to the console and adds a new line afterward.

is_key_pressed("key_char") Returns true if the key_char key is pressed. Returns false if not pressed.