Gravitator User Guide

Table of contents

Introduction

Gravitator is an interactive gravity simulator with editor of the world. It's focus is on simulation of large quantities of objects. This is possible because the objects fall into 2 categories: light and heavy. Heavy objects atract every other object, light objects don't attract any other object. Usually there are mostly tens of heavy and thousands of light objects. This enables simulation of space objects like galaxies and asteroid rings. To help you create such complex objects, Gravitator has an editor of the world capable of generating them for you. The editor is also capable of manipulating the objects and calculating stable orbit for them.

The Editor

The Editor in Gravitator enables you to create and manipulate objects in the world. By world I mean the objects which can be simulated. Besides that there are light and heavy objects, the editor uses the terms of "object" and "metaobject". Object is just a simple object. Metaobject is a group of objects with something similar, e.g. it's a galaxy, an asteroid ring, a group of objects forming a sphere etc.. The editor enables you to manipulate the objects and metaobjects.

Basics

Of course the editor allows you to perform basic operations as saving, loading a world and exiting.

Viewing and manipulating the world

The editor has four views on the world. The upper left is from the front, the upper right is the the right side, the lower left is from above and the lower right is a 3D view. The first 3 views are used for manipulating the world, the last one is for viewing the world from any direction.

The world is big 1000 units in each direction from the origin. The axis orientation as if looked from the front view is as follows: the x axis is horizontal, positive in the right direction, y axis is vertical, positive in the up direction and the z axis is the depth, it's positive in the direction to you.

Viewing the world

The upper left, right and lower left views are orthogonal, that means the view isn't perspectively correct. You can change your position in them by using the scrollbars. If you click in the arrows on the scrollbars, you move very slowly, that's for fine positioning. You can zoom in and zoom out in these view by clicking the Zoom in and Zoom out buttons next to them. If you want to return to the default position, then click the Center button. In these views you can see grid lines. The brightest 2 of them are the axis lines, which show the x, y, and z axis. The darker ones are drawn every 100 units. If you're zoomed in close enough, you'll see the darkest lines, which are drawn every 10 units.

To move and look around in the 3D view, you must use your keyboard. To be able to move in the 3D view, you must place the mouse cursor in it. Look in the preferences window to see the keys used for it. If you click the Center button, you return to the default position. Notice that the x, y and z axis are drawn, and the horizontal plane is also drawn.

Manipulating the world

Selecting and manipulating objects in this editor is quite classical as in every editor of some objects. You can click a object to select it, if you click where no object is then you deselect your previously selected object. You can drag a rectangle with your mouse to select all objects in the rectangle. If you hold Ctrl key pressed, then you add your current selection to the previous one. To move the selected object, just click on one of them and drag it to the new position.

You can also select and move metaobjects. To select a metaobject, click on its name in the list of metaobjects in the lower right corner of the window. You can select multiple metaobjects this way. In the metaobject list you can also set if the metaobject is visible by clicking on the checkbutton next to the metaobject's name. Invisible objects are of course invisible, and you also cannot select them, which is handy if you have too many objects in the world or you don't want to select objects in the metaobject.

Creating objects

To create a new object, select the desired metaobject type in the list of new objects in the upper right side of the window and click on the Create button. Then you will see a window with the objects properties a and you can position the object. Click in one of the orthogonal views to place it, then you can also move it like an ordinary object. You can set the objects properties in the object's window. In the upper part of the window you can see it's position. When you're happy with the object's properties and position, then click on the Ok button. If you don't want to create it, then click the Cancel button or close the object's window.

Metaobject types:

Simple Object

-this is just a simple object, in it's window you must set if it's a light or heavy object, set it's velocity, color (notice: the color values are in interval from 0 to 1), mass, size (diameter) and name

Homogenous Ball

-this is a homogenous ball of objects, that means this are objects evenly placed to a shape of a ball. You must set if the objects will be light or heavy, their velocity, color, mass and size. You must also set the name of the new metaobject, the diameter of the ball and the number of objects in the ball.

Homogenous Cylinder

-this is a homogenous cylinder of objects, that means this are objects evenly placed to a shape of a cylinder. You must set if the objects will be light or heavy, their velocity, color, mass and size. You must also set the name of the new metaobject, the diameter of the cylinder, the height of the cylinder and the number of objects in the cylinder.

Hollow Homogenous Cylinder

-this is a hollow homogenous cylinder of objects, that means this are objects evenly placed to a shape of a cylinder with a hollow in it's midle. You must set if the objects will be light or heavy, their velocity, color, mass and size. You must also set the name of the new metaobject, the diameter of the cylinder, the inner diameter of the cylinder, the height of the cylinder and the number of objects in the cylinder. This metaobject is especially usefull for creating rings of asteroids.

Ellipsoid

-this is an ellipsoid of objects, that means this are objects evenly placed to a shape of an ellipsoid. You must set if the objects will be light or heavy, their velocity, color, mass and size. You must also set the name of the new metaobject, the diameter of the ellipsoid in all 3 directions and the number of objects in the ellipsoid.

Spiral Galaxy

-this creates a spiral galaxy, that is a galaxy with stars in it's spirals and in it's centre. You must specify the velocity of the galaxy, the color of it's objects, the size (diameter) of it's objects and mass of it's central object. You must also specify the galaxy's name, if the objects will rotate clockwise or counterclockwise (as if looked from above), the diameter of the galaxy centre and number of objects in the centre. You must also specify the properties of the spirals of the galaxy, that is the total number of objects in all spirals, number of spirals, length of spirals, number of spiral's segments (the spirals aren't perfectly round, they are made of cylinders with decreasing diameter, these cylinders are the segments, the more segments you enter, the more round will the spiral be, but usually you don't need too much of them) and angle between segments(this specifies how much will the spirals turn).

Disk Galaxy

-this creates a disk galaxy, which is a galaxy with objects in it's centre and in a disk around it. You must specify the velocity of the galaxy, the color of it's objects, the size (diameter) of it's objects and mass of it's central object. You must also specify the galaxy's name, direction of rotation of it's objects (clockwise or counterclockwise). You must also specify height of the centre, diameter of the centre, number of objects in the centre, height of the disk, diameter of the disk and number of objects in the disk.

Elliptic Galaxy

-this creates an elliptic galaxy, which is a galaxy in the shape of an ellipsoid. You must specify the velocity of the galaxy, the color of it's objects, the size (diameter) of it's objects and mass of it's central object. You must also specify the galaxy's name, direction of rotation of it's objects (clockwise or counterclockwise). You must also specify height of the galaxy, diameter of the galaxy and number of objects in the galaxy.

Ellipsoid void

-this creates an ellipsoid void, which means that every object inside this void will be deleted. You must specify it's diameter in all 3 directions.

Sphere void

-this creates a sphere void, which means that every object inside this void will be deleted. You must specify it's diameter.

Cylinder void

-this creates a cylinder void, which means that every object inside this void will be deleted. You must specify it's diameter and height.

Editing objects

In the midle of the toolbar there are several icons for editing objects, you can rotate them, edit them, delete them and calculate a stable orbit

Rotating objects

-to rotate objects click on the Rotate button on the toolbar. First you must place the rotation axis in one of the orthogonal views. For example if you place it in the front view, you will be rotating the object in the front view around the z axis. When you've placed the axis, click on the Ok button. Then you can rotate the objects in the view where you placed the rotation axis by dragging the mouse. Notice that you can also rotate the selected metaobjects in the same way.

Editing objects/metaobjects

-to edit an object or metaobject click on the Edit button on the toolbar. In the appeared window you can set the new properties of the object or metaobject. You can edit only one object at a time, if you want to edit more then edit their metaobject. This is because you probably don't want to have half of an asteroid ring red a the other half blue...But if enough users will write me that they want to be able to edit more objects, then I will add that feature.

Delete objects/metaobjects

-clicking on the Delete button deletes the currently selected objects/metaobjects.

Calculate stable orbit

-to calculate a stable orbit for the selected objects/metaobjects, click on the Orbit button. Then select the object around which you want them to orbit and click Ok. Then rotate the orbit axis in the front and right view and choose whether should it rotate clockwise or counterclockwise. Notice that you cannot turn the rotate axis all the way around, you can mostly make it horizontal. It's because you don't need it, the same behaviour can be achieved by selecting the direction of orbit.

The simulation

To start the simulation click on the Start button in the toolbar. A window will appear where you can set the simulation properties. There are 3 view modes: Free look, Look at and Constant position. If you select the Free Look, you can freely move and turn in the world during the simulation. If you select the Look At mode, then the view points to the selected metaobject. You can also set a minimal and maximal distance to the metaobject on which you're looking. In the constant position mode the position and rotation in the world remains stable relatively to the selected object. You can also select the speed division in this window. Higher speed division means higher acurracy, but slower simulation. These settings can be changed also during the simulation. To start the simulation, press the Ok button.

In the simulation window you can see the simulated world and move in it. You move in it in the same way as in the 3D view (you must have the mouse cursor above it).The starting position and rotation is the same as the actual position and rotation in the 3D view.By clicking the Save button you can save the current state of the simulated world to a file. By clicking on the Restart button you can restart the simulation, the Pause button pauses the simulation and Start button starts a paused simulation. You can also change the speed division in the upper right part of the window. If you click on the Preferences tab in the top part of the window, you can change the view mode. Notice that you must press the ENTER key to confirm a new minimal or maximal distance. If you click on the Preferences tab then the simulation pauses.

Play a script

With using the gravitator_daemon program, you can save the simulation in a file, which is then called a script file. The advantage is that you can save only every n-th frame, so you can set a high speed division and stil see the simulation go fast. To play a script, click the Play script button in the toolbar. In the appeared window choose the file with the saved script. You can also set the frame delay, which specifies how often will the application load another frame. The time is in milliseconds. Notice that when you have too many objects in the script file, then the loading of the file takes some time, and you also need to leave some time for the GUI to be responsive, so with many objects the frames are displayed mostly few times per second. To start playing the script push the Ok button. The window playing the script is almost the same as the window showing the simulation.