On February 5th, we released updated versions of RINEARN Graph 3D/2D and VCSSL.
This release primarily focuses on two aspects: "Enhancing the Command-Line Features of RINEARN Graph" and "Adding English Support to VCSSL." In this article, we will delve into each of these updates!
Let's begin by introducing the updates to RINEARN Graph. There are two versions: "RINEARN Graph 3D" for 3D plotting and "RINEARN Graph 2D" for 2D plotting. This release features significant command-line enhancements for both RINEARN Graph 3D & 2D versions.
While it was possible to use RINEARN Graph via the command-line interface before, the options were quite limited. Users could only specify the file to open upon launch, and almost no other options were available. Consequently, all post-launch operations had to be performed manually through the GUI.
However, since RINEARN Graph supports an API for control, it's possible to perform complex operations automatically by writing a program that utilizes this API. Thus, the lack of functionality in the command-line interface could be compensated for by other means, and as a result, not much emphasis was placed on improving it.
Recently, we received feedback requesting enhancements to our command-line functionality, which led to a significant shift in our perspective and resulted in the updates included in this release.
Upon reviewing these requests, we realized:
The request also included hypothetical command-line examples, and the moment we saw them, we instantly recognized their potential utility and promptly implemented them in the next version (this release).
We'd like to take this opportunity to express our sincere gratitude to those who provided such excellent suggestions!
Let's put it to practical use.
To utilize RINEARN Graph via the command line, the entire software folder must first be placed in a fixed location.
For demonstration purposes (although not ideal), let's imagine we create a folder named "RINEARN" directly within the C drive of Windows and place the software folder inside it, as shown in the following:
The pivotal component here is the "bin" folder. Describing the location of this "bin" folder in text, it would be denoted as an "absolute path" like so:
We'll be using this absolute path shortly.
To utilize RINEARN Graph via the command line, you must register the absolute path of its "bin" folder in the Windows' environment variable named "Path" (or "PATH"). This process is commonly referred to as "setting the path."
For users of Windows 10 and 11, you can follow these steps to set the path. However, inadvertently deleting existing values could lead to various issues with your PC's operation. If this is your first attempt, we recommend seeking guidance from someone experienced or practicing on a new user account.
If you didn't find "Path" or "PATH" in step 3, follow these instructions:
3. If, after thorough inspection, you're certain that there's absolutely no "Path" or "PATH" variable in the list of "User variables for (your account name)", click "New" to open the "New User Variable" window.
Then, input "Path" in the "Variable name" field.
Note that if there's an existing variable with the same name, it will be overwritten without any warning! The previous content will be lost! If you're concerned, cancel the operation for now.
With these steps, you've completed the process known as "setting the path." When configuring an environment for various command-line operations on your PC, this process is almost inevitable, so you'll need to become familiar with it at some point. However, since accidentally overwriting existing settings can lead to serious issues, it's crucial to remain vigilant. Take your time and proceed with caution. It's recommended to double-check by pointing and confirming.
The instructions provided earlier are tailored for Windows users. If you're using a different operating system (OS) like Ubuntu or another Linux distribution, the process of "setting the path" will vary.
Furthermore, even within the same OS, the procedure differs based on the shell you're using, adding to the complexity of explanation. Thus, searching online for "set environment variable path (OS name)" or "set environment variable path (shell name)" is recommended to find guidance appropriate for your setup. You're likely to find many detailed and user-friendly guides.
Here's a brief overview for Linux users: Firstly, place the software in an a fixed location, such as "/usr/local/bin/.../rinearn_graph_3d_5_6_36/". Then, append the path of the "bin" directory to the PATH environment variable. Lastly, grant execute permissions to the "ring3d" file within the "bin" directory by executing the command "chmod +x ring3d" from within the "bin" directory.
Now that you've set the path, let's try launching it via the command line.
To perform various tasks via the command line, you'll need to open a command interface. On Windows, this could be "Command Prompt(cmd.exe)" or "PowerShell", while on other operating systems, it might be referred to as "Terminal" or something else.
The location of Command Prompt(cmd.exe) or PowerShell can vary depending on your Windows version, but recently, you can search for them from the taskbar at the bottom of the screen. If you frequently work with commands, pinning these command interfaces to the taskbar is convenient.
In other operating systems, the method of accessing the command interface differs. However, similarly, you can often find it by searching for terms like "Terminal" or "Shell." Note that typing the name of the shell like "bash" or "dash," may not bring up the desired result, as the individual implementation of a shell and the application that provides the "command input screen" are treated separately. Yes, it's a bit confusingc
Once you've launched the command interface, try entering the following:
This command launches RINEARN Graph 3D:
If you want to launch RINEARN Graph 2D instead, follow the same steps for setting the path (it's not bundled with RINEARN Graph 3D, so it requires separate path setting), and then, input:
Now, you'll see the following screen:
From here on, the usage of both the ring3d and ring2d commands is exactly the same (the only difference being whether the plotting result is a 3D or 2D graph), so we'll continue with the explanation using ring3d, which is more commonly used.
As a simple practical example, let's specify a data file and launch RINEARN Graph with it already open.
First, as a preparation, you need to "cd" into the directory containing your data file. This is akin to navigating through folders using a GUI, but in command-line form. In command-line operations, there's something like a current working directory (referred to as the "current directory"), and the cd command sets the specified folder as your working directory.
RINEARN Graph 3D comes with several sample data files, so let's navigate to that folder:
Now, this folder has been set as your working directory for command processing. When opening any data file, basically "cd" into the directory containing the file as a preparation. Without doing so, specifying the file directly in the command might require more complex paths.
It's also worth mentioning that when typing the folder path in the command line, pressing the Tab key after typing part of the path will auto-complete the rest of it (pressing it multiple times cycles through other completion options), making it quite convenient.
Furthermore, in most environments (both Windows and Linux), you can drag and drop a folder from the GUI into the command input screen. This action automatically inputs the absolute path, which might be easier than manual input. Preferences may vary among users regarding this method...
In this state, typing "dir" (for Command Prompt/cmd.exe) or "ls" (for PowerShell, Linux, etc.; note that "l" is a lowercase "L") will display a list of files in the working directory:
Let's try launching RINEARN Graph 3D with specifying "MembranePlotSample.txt" as an argument:
Similarly, if you press Tab after typing "ring3d Mem," the remaining part will be completed. This command line will plot the specified file as the 3D graph:
Next, let's try launching RINEARN Graph 3D with a data file as before, but this time, we'll save the graph as an image file and then exit immediately. To do this, enter the following command:
This command will close the graph window immediately, but a PNG image file named "temp.png" will be saved in the working directory.
Here, "--saveimg" is the option for saving the image, and "--quit" is the option for closing the software after the process is completed.
If you want to further adjust the graph's angle, range, or plotting options, such as whether to draw points or a surface, first prepare a configuration file and then specify it with a command.
For example, to load a configuration file named "TempSettings.ini" located in the working directory:
Here, use the "--config" option to specify the name of the configuration file. You can also specify relative or absolute paths.
The following image shows an example where a membrane (surface) plotting configuration file is specified:
On the other hand, specifying paths to configuration files used with the "Quick Settings" feature, located in the "RinearnGraph3DQuickSetting" folder of the software, can be cumbersome. For these files, instead of using "--config", you can use the "--quick" option, which allows you to specify the file by name only:
This "--quick" option was an idea from the person who requested us to expand the command-line features. It's likely to be very convenient. Much appreciated!
The examples provided above cover commonly encountered scenarios. For a full list of options or more details, you can view them by running:
We may continue to add options from time to time, so please check "--help" occasionally.
Next, letfs talk about VCSSL, another significant topic in this update.
VCSSL is a scripting language having C-like syntax, which also serves as a control language in RINEARN Graph 3D. In fact, itfs likely that more than half of VCSSL users utilize it for controlling RINEARN Graph 3D, although there are no exact statistics.
While itfs possible to control RINEARN Graph 3D using Java, setting up a Java development environment can be somewhat overkill for relatively light automation tasks. These tasks are predominantly handled by VCSSL, which might be likened to the position of a .plt file in gnuplot, plus a bit more.
Now, with the expanded command features and shell scripts, we've managed to cover some of the functionalities previously handled by VCSSL. However, delving into more complex tasks with shell scripts can quickly become arcane. VCSSL will continue to be the main tool for handling such areas. It's capable of handling much more complex tasks at a faster pace compared to shell scripts.
On the other hand, while VCSSL is intended for light use cases, it encompasses the basic features of programming languages, such as variable and function declarations, as well as if, for, and while statements. This has resulted in a substantial volume of documentation, significantly more extensive than that of ordinary applications. This volume had posed a challenge for English localization, with progress being excruciatingly slow, almost leaving us wondering when, if ever, it would be completed.
Then a turning point has come. Last year marked a pivotal moment for RINEARN, as we embarked on a project to translate technical documents into English with the assistance of ChatGPT, a large-scale language model AI. For more details on this initiative, please refer to the following article:
While initially experimental, this project quickly became routine, enabling us to efficiently translate lengthy and complex documents.
We've since refined our processes, adjusting the division of labor among the AIs and fine-tuning our workflow to balance speed and quality. This new approach has opened the possibility of completing the translation of all VCSSL documentation in a remarkably short time frame.
Efforts to translate VCSSL's documentation using this new workflow are well underway, with indications that the entire task may be completed by the first half of this year. This rapid progress was unexpected and somewhat hard to believe at first, yet it underscores how AI has revolutionized the field of technical documentation and beyond.
Now, we can't afford to overlook the translation of error messages in the VCSSL runtime environment. Since programming often involves "battles with errors," the translation of both documentation and error messages is essential; failing to update the latter would undermine the entire effort.
However, the current VCSSL runtime environment spans over one hundred thousand lines of code. Its architecture, predating the more streamlined Vnano (VCSSL nano), is notably complex, with error messages hardcoded throughout the codebase. (This complexity is why we're considering a complete re-implementation of the runtime environment in the next major version, VCSSL 4.)
Hence, to translate the error messages into English, we needed to painstakingly go through over one hundred thousand lines of code, finding the lines that are error messages and translating them one by one. This task would normally consume a vast amount of time. Yet, given the rapid pace of our documentation translation efforts, completing this task by early 2024 had become imperative to prevent it from becoming a bottleneck in our localization project!
So, over the New Year's break, despite being exhausted, we managed to complete this task through sheer determination. That's what's included in this update!
Let's delve into how to switch between languages. The simplest method is to download the VCSSL runtime environment from the language-specific official pages. This ensures that you get a version pre-configured for the selected language (Japanese or English), ready in your chosen language from the first launch.
Alternatively, within the "Console Window" that appears when running VCSSL programs, you can change languages by selecting "Settings" > "Select Language" from the menu bar. This option is especially useful if the runtime environment is installed on a shared PC, allowing users to switch languages according to their preferences.
----
That covers the updates for this release.
As a final note, as we have previously mentioned, we are considering a complete re-implementation of the VCSSL runtime environment from scratch for the next major version. We also plan to make this new version available as open-source.
The development timeline will likely follow the completion and release of the next major version of RINEARN Graph 3D (Ver. 6). We are already laying the groundwork for this exciting development and look forward to sharing more details with you in this "news" category!