Control and Automation with VCSSL

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.

What is VCSSL?

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.

» Learn more: What is VCSSL?

You can access the execution environment, programming guides, and more for free at the official VCSSL website:

• VCSSL Official Website
• Download the Execution Environment
• Programming Guides

Creating Programs

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.

Executing Programs

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.

Graph3D Library

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:

• Graph3D Library Specifications (Japanese, has not been translated yet)

Basic Program Examples

Now, let's actually control RINEARN Graph 3D using some functionalities of the Graph3D library!

Launching RINEARN Graph 3D and Obtaining its ID

First, let's start with a simple code that launches RINEARN Graph 3D:

// Import the "Graph3D" library to control RINEARN Graph 3D
import tool.Graph3D;

// Launch RINEARN Graph 3D and obtain its ID (x position, y position, width, height, title)
int graphID = newGraph3D(0, 0, 700, 700, "Graph");

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.

Obtaining the ID of an Already Launched RINEARN Graph 3D

Alternatively, you can use the getGraph3D function instead of newGraph3D:

import tool.Graph3D;

// Obtain the ID of an already launched RINEARN Graph 3D
int graphID = getGraph3D();

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.

Plotting Data Files on a 3D Graph

Below is the simplest program to plot the coordinate data file "test.csv" on a 3D graph:

import tool.Graph3D;

int graphID = newGraph3D(0, 0, 700, 700, "Graph");

// Plot the coordinate data file "test.csv"
setGraph3DFile(graphID, "test.csv");

Setting Line Plot Options

Next, here's a program to disable point plot options and enable line plot options:

import tool.Graph3D;

int graphID = newGraph3D(0, 0, 700, 700, "Graph");
setGraph3DFile(graphID, "test.csv");

// Disable point plot
setGraph3DOption(graphID, "WITH_POINTS", false);

// Enable line plot
setGraph3DOption(graphID, "WITH_LINES", true);

Exporting the Graph to an Image File

Here's a program to export the graph to an image file "test.png":

import tool.Graph3D;

int graphID = newGraph3D(0, 0, 700, 700, "Graph");
setGraph3DFile(graphID, "test.csv");

// Export the graph to an image file "test.png" (graph ID, image file name, image format)
exportGraph3D(graphID, "test.png", "PNG");

Advanced Program Examples

Next, let's explore some more complex and advanced examples.

Plotting Sequential Coordinate Data Files and Exporting to Sequential Image Files

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.

import tool.Graph3D;

int graphID = newGraph3D(0, 0, 700, 700, "Graph");

// Loop through variable i from 0 to 100
for (int i=0; i<=100; i++) {

    // Plot and save the i-th sequential coordinate data file to an image
    setGraph3DFile(graphID, "./test/test" + i + ".csv");
    exportGraph3D(graphID, "./test/test" + i + ".png", "PNG");

    // Sleep for 100 milliseconds (animation delay)
    sleep(100);
}

Reading Data Files, Performing Value Transformation, and Plotting - Using Arrays

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.

import tool.Graph3D;
import Math; // Necessary for using the sin function

// Open the coordinate data file "test.txt" in tab-separated read mode
int fileID = open("test.txt", READ_TSV);

// Get the number of lines in the file
int lineN = countln(fileID);

double x[lineN]; // Numeric array to store X values for all lines
double y[lineN]; // Numeric array to store Y values for all lines
double z[lineN]; // Numeric array to store Z values for all lines

// Loop through each line in the file
for(int i=0; i<lineN; i++){

    // Read one line of content and proceed to the next line
    // Returns an array containing the values of each column
    string[] columns = readln(fileID);

    // Treat the read column values as X, Y, Z values and store them in respective arrays
    x[i] = columns[0];
    y[i] = columns[1];
    z[i] = columns[2];

    // Apply transformation to z values using the sin function
    z[i] = sin(z[i]);
}

// Close the file access
close(fileID);

// Launch RINEARN Graph 3D and plot the x, y, and z arrays
int graphID = newGraph3D(0, 0, 700, 700, "Graph");
setGraph3DData(graphID, x, y, z);

Reading Data Files, Transforming Values, and Plotting - Using Temporary Files

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:

import tool.Graph3D;
import Math;

// Open the coordinate data file "test.txt" in tab-separated read mode
int inputFileID = open("test.txt", READ_TSV);

// Open a temporary file to write the transformed coordinate data in tab-separated format
int outputFileID = open("test_temp_converted.txt", WRITE_TSV);

// Get the number of lines in the file
int lineN = countln(inputFileID);

// Loop through each line in the file
for( int i=0; i<lineN; i++ ){

    // Read X, Y, Z values of one line and store them in an array
    string columns[] = readln(inputFileID);

    // Check if the array length is 0, indicating an empty line
    bool isEmptyLine = length(columns, 0) == 0;

    // If it's an empty line, write an empty line to the transformed file
    if(isEmptyLine){
        writeln(outputFileID, "");

    // If it's not an empty line, transform the values and write them to the transformed file
    } else {
        double x = columns[0];
        double y = columns[1];
        double z = columns[2];
        z = sin(z);
        writeln(outputFileID, x, y, z);
    }
}

// Close file access
close(inputFileID);
close(outputFileID);

// Launch LinearGraph 3D and plot the transformed temporary file
int graphID = newGraph3D(0, 0, 700, 700, "Graph");
setGraph3DFile(graphID, "test_temp_converted.tsv");

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.

Further Advanced Program Examples

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.