Welcome to Horus’s documentation!¶
Contents¶
Installation¶
Install on Ubuntu¶
Supported versions: 14.04, 15.04, 15.10, 16.04
System setup¶
sudo add-apt-repository ppa:bqlabs/horus-dev
sudo apt-get update
Official versions are hosted in ppa:bqlabs/horus: PPA Horus. Alpha, beta and rc versions are hosted in ppa:bqlabs/horus-dev: PPA Horus dev.
Note
A custom OpenCV version is used, because of the next reasons.
Install Horus¶
This command installs all the dependencies, including custom OpenCV libraries.
sudo apt-get install horus
Note
If user has no access to serial port, execute sudo usermod -a -G dialout $USER and reboot.
Install on Windows¶
Supported versions: 7, 10
Install Horus¶
Execute the installer and follow the wizard. This package contains all dependencies and also Arduino and FTDI drivers.
Reboot the computer to apply the changes.
Note
In Windows 10, if the application is blurred, follow these steps:
- Right click on the application and select Properties
- Go to Compatibility tab.
- Under Settings section, check Disable display scaling on high DPI settings
- Apply and close the window.
Getting started¶
Horus is a multiplatform application to experiment with the open 3D scanner Ciclop.
It provides a graphical interface that allows you to connect the scanner, control its devices, set scanning parameters, calibrate the scanner and scan 3D objects with Ciclop. It also includes a 3D scene of the point cloud obtained in real time.
It was created by bqlabs, the Department of Innovation and Robotics at BQ, developed in Python and released under the GPLv2 license.
Wizard¶
When you first open Horus, a Welcome window appears. This windows has two parts:
- Create new: it allows to launch the Wizard or any workbench.
- Open recent file: it provides direct access to the latest models (ply or stl).
Pressing over Wizard mode, an interactive menu appears for configuring the scanner step by step.
Connection window¶
This window contains the scanner connection, a preferences panel and the auto check process.
- Connect/Disconnect: connects the camera and the electronics of Ciclop. If a device can not be found, a notification message is thrown.
- Preferences: allows to modify the Camera ID and the Serial name of the scanner. Also the Luminosity. This setting can take High, Medium or Low for high, medium of low ambient light. The setting Invert the motor direction inverts all the motor angle commands.
- Auto check: in order to perform this process, putting the pattern over the platform is required, as shown in the picture. This process makes a full turn of the platform, and checks:
- Pattern detection: indicates whether the pattern is not detected correctly by luminosity or brightness problems.
- Motor direction: detects if the motor direction is reversed and how to correct it.
- Lasers detection: detects if the lasers have been connected properly and are working.
Note
The first time Auto check is pressed, a menu appears indicating if the lasers want to be aligned. This is for manually moving the orientation of the lasers until the emitted line is perpendicular to the platform. It requires an Allen wrench.
Calibration window¶
In this windows both the lasers calibration and the platform calibration are performed.
This calibration process computes the planes in the space respect to the camera for each laser, as well as the spatial relation between the turntable and the optical center of the camera.
Note
The first time the calibration is performed, Origin pattern distance must be set. This distance is fundamental for the platform’s calibration, because it indicates the real relation between the position of the pattern’s sticker and the base.
Scanning window¶
In this window, scanning parameters are set:
- Resolution: it is related to the number of steps per revolution of the motor.
- High: 800 steps (0.45º)
- Medium: 400 steps (0.9º)
- Low: 200 steps (1.8º)
- Laser: selects left laser, right laser or both.
- Capture texture: enabling this option captures the real color of the object. Otherwise the point cloud has an uniform fake color.
Once the Wizard is completed, access the main window.
Menu¶
File¶
- Launch wizard: opens the Wizard.
- Open model: opens a 3D model (ply point cloud or stl mesh).
- Save model: saves the point cloud of the 3D scene in ply format.
- Clear model: removes the current 3D model from the 3D scene.
- Open profile: loads all the control, adjustment and scanning parameters.
- Save profile: saves all the control, adjustment and scanning parameters in JSON format.
- Reset profile: resets all the control, adjustment and scanning parameters to the default values.
- Open calibration: loads all the calibration parameters.
- Save calibration: saves all the calibration parameters in JSON format.
- Reset calibration: resets all the calibration parameters to the default values.
- Export log: saves a log file with the registry of the previous commands.
- Clear log: removes the log file. It is automatically removed each 7 days.
- Exit: closes the application.
Edit¶
Preferences: opens the complete preferences window:
- Connection section: Camera ID, Serial name and Baud rate.
- Adjustment section: Luminosity and Invert the motor direction.
- Firmware section: allows to upload the default or a selected firmware to BT ATmega328 and Arduino UNO boards. Also, it can clear EEPROM before uploading the firmware.
- Language section: allows to select the application’s current language.
Note
The Firmware section is only enabled if the scanner is disconnected.
View¶
This menu shows and hides the Scanning workbench panels: the configuration panel, the video and the 3D scene.
It also contains the Advanced mode option, that enables advanced options in Calibration workbench.
Help¶
In this menu you can open the Welcome window, check for updates and to access to project’s web resources.
Scanning¶
To start scanning press the Play button. Also the process can be stopped, paused and resumed.
During the scanning, the progress is shown in the bottom of the scene.
You can navigate in the 3D scene using the following shortcuts:
| Action | Shortcut 1 | Shortcut 2 |
| Default views | Home / PgUp / PgDn / End | |
| Rotate | Left click | Shift + Up/Down |
| Rotate horizontally | Up / Down | |
| Rotate vertically | Left / Right | |
| Vertical shift | Ctrl + Mouse wheel | Ctrl + Up / Down |
| Reset vertical shift | Dobule left click | |
| Traslation | Shift + Left click | |
| Zoom | Mouse wheel | Shift + Up /Down |
| Delete object | Right click + Delete object | Del |
| Quit program | Ctrl + Q |
Upon completion of the scanning process, the object can be saved in File > Save model. The point cloud is saved in ply format.
Workbenches¶
Control¶
This workbench is used to test the scanner components: camera, lasers and motor.
Camera¶
In this section you can adjust the brightness, contrast, saturation and exposure of the camera.
Also it allows to capture and save images from the camera in png format.
Laser¶
In this section you can turn on and off the lasers. When leaving the workbench the lasers are automatically turned off.
Motor¶
In this section you can move the motor to an absolute angle, with a specific speed and acceleration. These values affect only to this workbench.
Also the motor can be enabled or disabled and the position stored inside the firmware reseted.
Gcode¶
This section contains a terminal that allows to communicate with the firmware through Gcode commands.
Adjustment¶
In this workbench, camera capture and image processing parameters are adjusted for the different states of the system. The current state and its changes are displayed in the video wall in real time.
Scanning adjustments¶
These settings are applied during the scanning process.
Capture¶
In this section you can adjust the parameters of the capture during the scanning process. These parameters must be adjusted with the object to be scanned.
The Texture mode contains the settings used to capture the texture/color of the scanned object. These are: brightness, constrast, saturation and exposure.
The Laser mode contains the settings used to capture and detect the laser over the scanned object. These are: brightness, constrast, saturation, exposure and background removal. The Remove background option improves the laser detection by consuming twice as long.
Segmentation¶
In this section you can adjust the parameters for the laser stripe segmentation during the scanning process.
- Draw line: show the computed lines in red from the segmented laser image.
- Threshold: remove all pixels which intensity is less that the threshold value.
- Blur: blur with Normalized box filter. Kernel size: 2 * value + 1.
- Window: filter pixels out of 2 * window value around the intensity peak.
- Refinement: apply None or SGF algorithms for line smooth. SGF produces continous surfaces.
Calibration adjustments¶
These settings are applied during the calibration processes.
Capture¶
In this section you can adjust the parameters of the capture during the calibration process. These parameters must be adjusted with the calibration pattern.
The Pattern mode contains the settings used to capture the pattern. These are: brightness, constrast, saturation and exposure.
The Laser mode contains the settings used to capture and detect the laser over the pattern. These are: brightness, constrast, saturation, exposure and background removal. The Remove background option improves the laser detection by consuming twice as long.
Segmentation¶
In this section you can adjust the parameters for the laser stripe segmentation during the calibration processes.
- Threshold: remove all pixels which intensity is less that the threshold value.
- Blur: blur with Normalized box filter. Kernel size: 2 * value + 1.
- Window: filter pixels out of 2 * window value around the intensity peak.
- Refinement: apply None, SGF, RANSAC algorithms for line smooth. SGF produces continous surfaces. RANSAC produces flat surfaces.
Calibration¶
This workbench contains all the scanner calibration processes.
Pattern settings¶
This section contains the calibration pattern features:
- Pattern rows: number of corner rows in the pattern. Default value 6.
- Pattern columns: number of corner columns in the pattern. Default value 11.
- Square width: default value 13 mm.
- Origin distance: minimum distance between the origin of the pattern (bottom-left corner) and the pattern’s base surface in mm. There is no default value because it depends on the physical pattern.
Autocheck¶
This section contains the auto check process in which is detected whether the pattern, motor and lasers are configured properly.
The pattern should be placed as shown in the picture. If the process ends successfully, the pattern will be placed perpendicular to the camera. Otherwise, a notification will be displayed.
Laser calibration¶
In this section, the laser’s planes are calculated. Each plane is defined by a normal vector and the minimum distance from the plane to the optical center of the camera.
To begin the calibration, the pattern must be placed perpendicular to the camera, as shown in the picture. At any time you can cancel the calibration and the pattern will return to its initial position.
Finally the result is shown numerically and depicted in 3D. Also, the dispersion of the captured points during calibration appears. This value must be less than 0.1 mm. You can accept or reject the calibration result.
Platform calibration¶
In this section, the homogeneous transformation matrix from the rotation center of the turntable with respect to the camera system is calculated. This matrix is composed by a rotation matrix and a traslation vector in mm.
To begin the calibration, the pattern must be placed perpendicular to the camera, as shown in the picture. At any time you can cancel the calibration and the pattern will return to its initial position.
Finally the result is shown numerically and depicted in 3D. You can accept or reject the calibration result.
Once this process is completed, the scanner is calibrated.
Video settings (advanced)¶
This is an advanced section. It contains the rotation flags for the video. Also you can set the camera resolution in px.
Hint
If a wrong resolution is set, the nearest resolution is recommended. Also, you can go back to the latest resolution.
Note
In Mac OS the resolution can not be set in runtime because of its OpenCV version.
Camera calibration (advanced)¶
This is an advanced section. Default values are recommended.
To begin the calibration, press the “space” key to capture the pattern in different positions. Once taken all the captures, the calibration starts automatically. You can reset the taken captures at any time.
Warning
If camera intrinsics values are modified, laser and platform calibrations must be performed again.
Note
To enable the advanced mode go to the menu View > Advanced mode.
Scanning¶
This workbench is where the 3D scanning process is performed. This process generates a three dimensional point cloud from a physical object. It has three components:
- Settings panel
- Video wall
- 3D scene
Through the menu View these panels can be shown or hidden.
Settings panel¶
Scan parameters¶
- Capture texture: enabling this option captures the real color of the object. Otherwise the point cloud has an uniform fake color. If this option is disabled, the process is faster and the color used is the one defined in the Point cloud color section.
- Use laser: selects left laser, right laser or both.
Rotating platform¶
- Show center: shows the center of the platform using the current calibration values.
- Step: is the angle increased in each scan iteration. The smaller the step, the greater radial resolution, and also more scanning time. The default value is 0.45º, that is 800 steps per revolution.
- Speed: is the motor speed in degrees per second. Te default value is 200 º/s.
- Acceleration: is the motor acceleration in degress per secon squared. The default value is 200 º/s².
Point cloud ROI¶
In this section the ROI (Region of interest) is defined. It is a cylindrical volume in the point cloud and a rectangle in the video.
- Use ROI: enabling this option applies the ROI. This region is the one being scanned both in the video and in the point cloud. All information outside won’t be taken into account during the scanning process.
- Diameter: ROI diameter in mm. The default value is 200 mm.
- Height: ROI height in mm. The default value is 200 mm.
Point cloud color¶
In this section is selected the color for the point cloud when no texture is captured.
Note
The Settings panel is hidden during the scanning process.
Video wall¶
In this window, two states are distinguished: while not scanning, it shows the video in texture mode. When the scan starts, you can select several views corresponding to the different stages of the image processing.
- Texture
- Laser
- Gray
3D scene¶
This section is a three-dimensional scene where the scanned point cloud (model) is shown. Also it allows to view meshes in stl format.
To start scanning press the Play button. Also the process can be stopped, paused and resumed. During the scanning, the progress is shown in the bottom of the scene.
You can navigate in the 3D scene using the following shortcuts:
| Action | Shortcut 1 | Shortcut 2 |
| Default views | Home / PgUp / PgDn / End | |
| Rotate | Left click | Shift + Up/Down |
| Rotate horizontally | Up / Down | |
| Rotate vertically | Left / Right | |
| Vertical shift | Ctrl + Mouse wheel | Ctrl + Up / Down |
| Reset vertical shift | Dobule left click | |
| Traslation | Shift + Left click | |
| Zoom | Mouse wheel | Shift + Up /Down |
| Delete object | Right click + Delete object | Del |
| Quit program | Ctrl + Q |
To load, save or reset the 3D model, access from the menu File.
Scanner components¶
Camera¶
Supported cameras¶
Logitech C270¶
HD USB webcam with fixed focus.
| Name | Value | Setting |
| Width | 1280 px | camera_width |
| Height | 960 px | camera_height |
| Frame rate | 30 fps | frame_rate |
| Rotation | Yes | camera_rotate |
| Horizontal flip | Yes | camera_hflip |
| Vertical flip | No | camera_vflip |
| Focal length x | 1430 px | camera_matrix |
| Focal length y | 1430 px | camera_matrix |
| Optical center x | 480 px | camera_matrix |
| Optical center y | 620 px | camera_matrix |
| Distortion | No | use_distortion |
Image controls¶
| Name | Range | Setting |
| Brightness | 0-255 | brightness_ |
| Contrast | 0-255 | contrast_ |
| Saturation | 0-255 | saturation_ |
| Exposure | 1-64 | exposure_ |
These parameters have different values for each situation:
- Capture texture
- Pattern detection
- Laser detection over the object
- Laser detection over the pattern
Therefore, for each case the optimum values can be set.
Flush buffer¶
OpenCV is used to manage the camera. It wraps all the functionality to allow easy access.
At the low level driver, each operating system has different behavior regarding to the buffer of stored images. Moreover, if the exposure time is set over the frame rate (33 ms), buffer filling may vary if image controls are being updated. This may cause synchronization problems between the laser and the camera. Instead of using a long delay to reach the synchronization, a better approach is implemented using custom flush values.
| Name | OS | Value | Setting |
| Texture flush | Linux | 3 | flush_linux_texture |
| Laser flush | Linux | 2 | flush_linux_laser |
| Pattern flush | Linux | 3 | flush_linux_pattern |
| Texture flush | Windows | 4 | flush_windows_texture |
| Laser flush | Windows | 3 | flush_windows_laser |
| Pattern flush | Windows | 4 | flush_windows_pattern |
| Texture flush | MacOSX | 4 | flush_darwin_texture |
| Laser flush | MacOSX | 3 | flush_darwin_laser |
| Pattern flush | MacOSX | 4 | flush_darwin_pattern |
Note
In Linux, a custom OpenCV version is used, because of the next reasons. In Windows and Mac, standard 2.4.9 version is used.
Troubleshooting¶
Focus image¶
Logitech C270 camera is not focused at the scanner working distance (about 300 mm), but it is focused at a longer distance. This may cause inaccurate pattern detection and worse calibration values.
To improve that, the camera can be re-focused manually:
- Remove the electronics: the camera can not be removed if the board is fixed.
- Disassemble the camera: remove the 3 screws and the front cover.
- Move the lens to break up the glue.
- Put the camera into the scanner.
- Put the pattern on the middle of the platform.
- Open the video and move the focus until the pattern is focused.
- Assemble again the camera and the rest of the scanner.
In this video the camera manual focus is explained.
Board¶
Horus Firmware¶
The firmware is an adaptation of Grbl. Releases are hosted here: https://github.com/bqlabs/horus-fw/releases.
It can be uploaded in Preferences > Upload firmware.
Troubleshooting¶
Board not detected¶
Sometimes Arduino UNO board is not detected correctly, specially if you are using Windows 10 or strange clones. First of all, follow this steps to ensure that your board and your operating system are working fine together:
- Follow this guide to install the drivers and the Arduino IDE: https://www.arduino.cc/en/Guide/Windows.
- Upload the blink example. If it doesn’t work go to: https://forum.arduino.cc/ to find a solution.
Then if the led is blinking is time to upload the Horus firmware. You have two options:
- In Horus GUI, go to Preferences. Select your board and press Upload firmware.
- In Arduino IDE, download the source code (https://github.com/bqlabs/horus-fw) and upload the file horus-fw.ino.
Hint
If you have any problem related to the board or the shield please put it here: https://github.com/bqlabs/horus/issues to update this manual.
Lasers¶
Supported lasers¶
Line laser¶
Red Class 1 line laser.
| Name | Value |
| Wavelength | 650 nm |
| Voltage | 5 V |
| Working distance | 300 mm |
| Output aperture | 3 mm |
| Output power | 2.5 mW |
| Fan angle | > 60 º |
| Body diameter | 8 mm |
| Body length | 26 mm |
| Wire length | 250 mm |
| Security class | 1 |
| TÜV certificate | Yes |
Warning
Only Class 1 lasers according to IEC 60825-1:2014 are recommended to ensure eye safety. The emission limits for this wavelength must be less than 390 uW.
Gcodes¶
M71¶
Switch on the laser specified in the T command.
| Example: | M71 T2 |
|---|
Note
Lasers are switched off automatically after 255 seconds as a safety measure.
Troubleshooting¶
Laser not detected correctly¶
If the laser is not detected correctly:
- Improve the environment light conditions.
- Adjust the camera settings in Adjustment workbench:
- Scan capture > Laser for the laser over the scanning object.
- Calibration capture > Laser for the laser over the pattern.
Motor¶
Supported motors¶
Nema 17¶
Bipolar stepper motor.
| Name | Value |
| Phase | 2 |
| Voltage | 2.55 V |
| Step angle | 1.8º |
| Fan angle | > 60 º |
| Shaft height | 22 mm |
| Body height | 40 mm |
| Wire length | 600 mm |
| Chamfer | Yes |
Gcodes¶
G1¶
Perform an angular movement. Using the F command, the angular speed is set to the specified value in degrees per second. Also with the X command, the motor moves to the specified absolute position in degrees.
| Examples: | G1 F200, G1 X-90 |
|---|
G50¶
Reset all positions to zero. It is recommended to be executed after M18 to avoid the oscillation anchor.
M17¶
Enable the motor. It remains enabled even after sending G1 commands.
Warning
If the motor is enabled for a long time, the driver and the motor can overheat and even break.
M18¶
Disable the motor. It remains disabled even after sending G1 commands.
Troubleshooting¶
Reversed direction of rotation¶
Motor rotation must turn in a counterclockwise direction with positive angles. If it turns in reverse, probably the connector is connected in the wrong way. This can be solved by editing the parameterinvert_motorin Preferences > Invert the motor direction.
Strange movements¶
To avoid possible strange movements in the motor:
- Make sure the motor step is 1.8º.
- Put all the jumpers in the Zum Scan board to enable micro-stepping.
- Adjust the electrical current with the potentiometer in the pololu driver. Recommended values are about 200 mA.
Pattern¶
Supported pattern¶
Chessboard patterns¶
| Name | Value | Setting |
| Rows | 6 | pattern_rows |
| Columns | 11 | pattern_columns |
| Square width | 13 mm | pattern_square_width |
| Origin distance | > 0.0 mm | pattern_origin_distance |
Note
These values can be set in Calibration workbench > Pattern settings.
Warning
It must be an odd number of columns in order to define an unique origin of the pattern.
Origin distance¶
The origin distance is the minimum distance between the origin of the pattern (bottom-left corner) and the pattern’s base surface. This value is used to define where is the pattern with respect to the turntable.
Pattern detection¶
When the pattern is correctly detected, the following colored dots and lines are drawn.
