RINEARN Graph 3D supports control through the scripting language VCSSL, which, when utilized effectively, enables the automation of tasks such as plotting sequential files and converting data before plotting, among others.
VCSSL is a lightweight programming language designed for tasks such as data visualization, computational processing, and tool creation. Its syntax is similar to that of the C programming language, making it easy to learn.
You can access the execution environment, programming guides, and more for free at the official VCSSL website:
Since VCSSL is a scripting language, programs can be simply created by typing text in a general-purpose text editor. Notepad or similar simple tools can be used, though they are not ideal for this purpose. However, there are many editors available that are better suited for programming.
If you're using Windows, a recommended editor is Sakura Editor. By utilizing the syntax highlighting settings for C/C++, you can enhance the readability of VCSSL programs through color coding. Moreover, with the VCSSL runtime installed on your PC, you can execute programs directly from Sakura Editor by pressing Ctrl + B.
To execute VCSSL programs, an execution environment is required, which is included by default in RINEARN Graph 3D.
Simply open the "Program" menu on the menu bar, and select the desired VCSSL program for execution. The default location for program selection is the "RinearnGraph3DProgram" folder, so it's convenient to keep frequently used programs there.
Alternatively, you can obtain a standalone execution environment, VCSSL runtime, from the official VCSSL website. If you regularly create programs, installing the VCSSL runtime on your PC may be more convenient, particularly if executing programs from the RINEARN Graph 3D menu bar becomes cumbersome during development.
To control RINEARN Graph 3D from VCSSL, you will use the "Graph3D" library.
Graph3D library is specifically designed for drawing 3D graphs in VCSSL, using RINEARN Graph 3D as the default graph drawing environment. This seamless integration is possible because both VCSSL and RINEARN Graph 3D are developed by the same studio, RINEARN.
Therefore, you can control RINEARN Graph 3D without any complex linking configurations by simply utilizing the Graph3D library within your VCSSL program.
For detailed specifications of the Graph3D library, please refer to the following page:
Now, let's actually control RINEARN Graph 3D using some functionalities of the Graph3D library!
First, let's start with a simple code that launches RINEARN Graph 3D:
As shown above, calling the newGraph3D function launches RINEARN Graph 3D and returns the identification number (ID) assigned to it. This ID is essential when you want to control multiple instances of RINEARN Graph 3D within a single VCSSL program.
Functions used to control 3D graphs, such as setGraph3DFile, require this ID as the first argument to ensure clarity about which 3D graph the control commands are targeting.
Alternatively, you can use the getGraph3D function instead of newGraph3D:
When you execute this program from the "Program" menu of an already launched RINEARN Graph 3D, the getGraph3D function returns the ID for controlling that specific instance. This is useful when you do not want to launch a new 3D graph window.
Additionally, if there is no RINEARN Graph 3D currently running when the getGraph3D function is called, it will not cause any errors; instead, it will launch a new RINEARN Graph 3D window.
Below is the simplest program to plot the coordinate data file "test.csv" on a 3D graph:
Next, here's a program to disable point plot options and enable line plot options:
Here's a program to export the graph to an image file "test.png":
Next, let's explore some more complex and advanced examples.
The following program sequentially loads and plots coordinate data files "test0.csv" through "test100.csv" from the "test" folder located in the same directory as the VCSSL program. It then exports the plots to image files "test0.png" through "test100.png".
By commenting out the exportGraph3D line, the program will simply animate the series of files without saving them as images.
Let's tackle a common scenario in data analysis: reading coordinate values from a file, applying transformations, and plotting them.
This example and the next assume that the data files are formatted in a three-column layout, delimited by tabs, as shown below:
The following program opens this file, stores all coordinate values into arrays, converts the z-values to sin(z), and plots the converted coordinates using the setGraph3DData function.
The above program is simple, but there are many cases where file conversion processes cannot be straightforward due to the complexity of the content.
For example, consider files that contain empty lines, header lines, or comment lines that must be preserved. In such cases, it is relatively easy to create a temporary file, write the conversion results to it, and then plot it on the graph.
Below is an example of processing a file "test.txt", similar to the one before, but with the requirement to maintain empty lines within the file:
When you execute the above program, the conversion results are written to the temporary file "test_temp_converted.txt", which is then plotted on the graph.
This example has become more complex compared to the previous one. For file conversion involving non-numeric lines such as comment lines or header lines, even more complicated processing may be required than what was shown above. This might necessitate a certain level of programming experience with string manipulation.
In practical data analysis and conversion scenarios, it's common to adjust the read-in processing on a case-by-case basis to accommodate the "quirks" of the file. One of the reasons RINEARN Graph 3D supports VCSSL by default is to address such cases.
On the VCSSL official website's code archive, various programs are available for public access. Among them, there are examples that utilize the Graph3D library to tackle more advanced tasks. Let's highlight some of them.
| Tool to Animate 3D Graphs from Sequential Files | |
|
This tool represents an advancement of the earlier mentioned program, which reads sequential files to animate 3D graphs and outputs images. It has now been developed into a GUI tool and is bundled with RINEARN Graph 3D by default. |
| Circular Wave Animation Display | |
|
This program enables visualization of circular wave graphs in animation while allowing users to manipulate amplitude, wavelength, and period using sliders. |
| Lorenz Attractor | |
|
Using a 4th-order Runge-Kutta method, this program calculates and plots the solution curves of the Lorenz equations. Parameters can be adjusted using sliders, and the graph updates in real-time. |
Many more diverse programs are available on the code archive, so feel free to explore and find ones that may be useful for your needs.