The ARSandbox is an application provided by UC Davis https://arsandbox.ucdavis.edu/. It's used on a Linux based computer that control's a projector and an Xbox Kinect camera. Using the two, it can project and measure the sand in the box and draw the geological contours of the map in real time.
"Why do I want this installed on CentOS if the developer shows installing on Ubuntu?"
This is a common issue within the world of Open Source Software. Many developers make the choice to use Ubuntu to develop their applications. It's a choice based on that Ubuntu has a good desktop environment to develop applications with.
However, in Academics and Academic research programs, many Systems/IT Environments are heavily invested in Red Hat Enterprise Based Operating systems. So Ubuntu is something that isn't as common in the Data Center and skill-sets of IT. As a System's person myself, I do what I can to facilitate this gap between developer's and systems people. This helps everyone as when a researcher comes to IT for help with a project (like this one ARSandbox) it makes it more difficult for IT to try to manage an Operating System they aren't as familiar with.
So, using my expertise with Red Hat based systems and kickstart I have built this procedure so to be able to give back to the open source project (ARSandbox). This contribution will allow other researchers who would like to utilize this research to be able to install and run it on a platform that IT is more familiar with so as to be able to get help from their local IT staff at their organization.
It also helps minimize the steps needed to get this up and running since this automatic procedure will compile and build the software as part of the Operating System installation. This may reduce the need for assistance from IT to assist faculty with their own attempts to build one of these platforms.
To make this process as simple as possible, to build the Linux host all you need to do is download the CentOS 7 minimal ISO installer.
You can download it from one of these mirrors
Burn the ISO to a CD so you can boot from it. This is a useful document for burning ISO's.
On a PC, you can right click the ISO file and choose "Burn image to disk".
Most PC BIOS's will allow you to temporarily boot from another medium (USB, CD, etc) by pressing the F12 (or possibly another F key) when the system boots up. This will provide you with a menu of choices to boot from. Select the CDROM/DVD device.
The machine will get built according to this ARSandbox machine kickstart file
In order to get the installer to use this configuration we need to supply additional arguments to the bootloader.
after the word "quiet" add the following:
ks=https://raw.githubusercontent.com/hamhpc/ARSandbox/master/ks_arsandbox.cfg
Press Enter to continue.
This step may be optional depending on how your disks are discovered. If it detects a previously installed OS you'll need to tell the software to over-write this old installation.
While the machine is building itself .. take a break as this could take a few minute to complete. Once it's up we'll be ready to log in and configure the ARSandbox software and Devices.
Make sure you remove the CDROM before rebooting the machine.
The host is configured to automatically log into the arsandbox user account.
Right click the desktop and choose Konsole
Now that the basic operating system is installed you'll most likely want to get and install the video card driver for your particular card. Most likely out of the box the operating system is using a more generic driver and can't take advantage of the hardware acceleration of the Graphis card. Using the driver from the manufacture is generally preferred since it can fully utilize your hardware.
I won't go into the details of installation of the driver for your card here. While this will work out of the box with the basic driver you may find the advanced features (ie. water) as well as the resolution of the projected image won't be as good as using the correct driver from the manufacture.
A useful command to determine your card is the lspci command. Use it to see what devices are connected to the PCI bus.
[root@localhost]# lspci | grep -i VGA
01:00.0 VGA compatible controller: Advanced Micro Devices, Inc. [AMD/ATI] Cedar [Radeon HD 5000/6000/7350/8350 Series]
[root@localhost]#
Now that the operating system is installed you can use the following steps to calibrate and configure the devices.
Plug in your first-generation Kinect device and download intrinsic calibration parameters directly from its firmware. In a terminal window, run:
% sudo /usr/local/bin/KinectUtil getCalib 0
Note: This might ask you for your password again; if so, enter it (arsandbox) to continue.
Align your camera so that its field of view covers the interior of your sandbox. Use RawKinectViewer to guide you during alignment. To start it, run in a terminal window:
% sudo /usr/local/bin/RawKinectViewer -compress 0
While looking at the camera image in RawKinectViewer make sure the Kinect sensor is lined up with the sides of the sandbox. If the sandbox appears off from the viewport of the Kinect camera, tilt the Kinect camera until you can get these aligned.
This step will calculate the plane (base level) of the SandBox.
If your box has sand in it put a sheet of cardboard or other flat surface over the top of the box. If you use this method, remember to measure the distance (in cm) from the cardboard to the bottom of the sandbox. In this case, the bottom of the box was 16cm below the cardboard. When you get the base plane equation from the rest of this step remember to add the value, from your measurement, to the last number in the equation. It's all explained in the following video:
Calculate your sandbox’s base plane, by following the instructions in the AR Sandbox Calibration video (above) that shows all required calibration steps in one. You can use the already-running instance of RawKinectViewer.
Select average frames
Extract Planes
You need to enter the base plane equation (and the 3D sand surface extents in the next step) into the BoxLayout.txt file in /usr/local/etc/SARndbox-2.3
% cd /usr/local/etc/SARndbox-2.3
% kwrite BoxLayout.txt
Now enter the base plane equation as described in the video. To copy text from a terminal window, highlight the desired text with the mouse, and then either right-click into the terminal window and select “Copy” from the pop-up menu that appears, or press Shift-Ctrl-c. To paste into the text editor, use the “Edit” menu, or press Ctrl-v.
Pro tip: The quickest way to copy&paste text from any window into any other window is:
- Highlight text in source window with the mouse.
- Move mouse to destination window and to the location where you want to paste the text, and click the middle mouse button.
The equation will look something like the following from the RawConnectViewer output in the terminal:
(-0.0076185, 0.0271708, 0.999602) = -98.0000
Be sure to replace the = with a , and add the measured value from the cardboard to the bottom of the sandbox from above. The last number in this sequence is the depth. So in our example -98 becomes -114. So the first line of our BoxLayout.txt file has this:
(-0.0076185, 0.0271708, 0.999602), -114.0000
Note: Be sure to remove the cardboard covering the sandbox from the previous step.
In the newly-released Kinect-3.2 package, this can be done inside RawKinectViewer as well by following the instructions in this video, starting at 4:10. Make sure to measure the box corners in the order lower-left, lower-right, upper-left, upper-right. After you have copied the box corner positions into the text editor as described in the video, save the file (via the “File” menu or by pressing Ctrl-s), and quit from the text editor (via the “File” menu or by pressing Ctrl-q).
In the terminal window from where you executed the RawConnectViewer you'll have the following four corner points:
( -48.6846899089, -36.4482382583, -94.8705084084)
( 48.3846899089, -34.3992382583, -89.3885084084)
( -50.6746899089, 35.8072382583, -97.4085084084)
( 48.7946899089, 36.4782382583, -91.7415084084)
Add these to the BoxLayout.txt file after the plane equation from the last step. No changes need to be made to the formatting from the terminal.
You can now Exit RawKinectViewer and save BoxLayout.txt
Align your projector such that its image fills the interior of your sandbox. You can use the calibration grid drawn by Vrui’s XBackground utility as a guide. In a terminal, run:
% /usr/local/bin/XBackground
After the window showing the calibration grid appears, press the “f11” key to toggle it into full-screen mode. Ensure that the window really covers the entire screen, i.e., that there are no title bar, desktop panel, or other decorations left.
Press Esc to close XBackground’s window when you’re done.
Determine the resolution that your projector is running at. In our case it is running at 1024 X 768. You will also need to have created the calibration tool. This consists of:
- CDROM Disk
- Coat Hanger
- blank sheet of paper
Create the calibration tool. This is made up of a CD disc with blank sheet of paper glued to it. On the paper you have two lines perpendicular to one another, one horizontally and one vertically so that they make up a + sign with a point in the center of the disc. Using a wire coat hanger proved to work the best to form a handle to use when taking reference points.
Calibrate the Kinect camera and the projector with respect to each other by running the CalibrateProjector utility:
% /usr/local/bin/CalibrateProjector -s <width> <height>
where are the width and height of your projector’s image in pixels. For example, for an XGA projector like the recommended BenQ, the command would be:
% /usr/local/bin/CalibrateProjector -s 1024 768
Very important: switch CalibrateProjector’s window to full-screen mode by pressing F11 before proceeding. Then follow the instructions in this video, starting at 10:10.
Create a capture tool and bind it to the "2" key. This will allow you to re-capture a background image after you've changed the topography of the sand.
Pressing the "1" key will take each reference point by lining up your crosshairs from the CD to the lines drawn in the sandbox.
Finally, run the main AR Sandbox application:
% /usr/local/bin/SARndbox -uhm -fpv &
- Vrui is located at https://github.com/KeckCAVES/Vrui
- Kinect is located at https://github.com/KeckCAVES/Kinect
- SARndbox is located at https://github.com/KeckCAVES/SARndbox
- Complete Installation Instructions
- The arsandbox user password is "arsandbox"
- The original sources are installed in /opt
- The applications are compiled in /opt and then installed into the /usr/local directories.
- The user arsandbox owns the files in /opt and /usr/local so that account has full control over these installations to make changed as needed.
- SELinux and Firewall is disabled so remember this isn't a secure as it could be if you leave it plugged into the network.
- The user arsandbox is also a sudoer.. meaning if you need root access you can become root using the following command:
% sudo su -