Package Summary

The z_laser_projector package is a ROS wrapper for ZLP1 Z-LASER Projector, that makes it fully compatible with all available sensors and devices running over the ROS-Industrial project. This package provides libraries that allow the user to operate the device and simplify the task of developing further advanced features, such as augmented reality applications.

  • Maintainer status: maintained
  • Maintainer: Rafael Luque <rluque AT catec DOT aero>, Ines M. Lara <imlara AT catec DOT aero>
  • Author: Rafael Luque <rluque AT catec DOT aero>, Ines M. Lara <imlara AT catec DOT aero>
  • License: Apache 2.0
  • Source: git (branch: melodic)


The ZLP1 is an eye-safe laser projector (laser class 2M). The system projects figures and patterns as an optical guidance system for human operator tasks. Such guidance can be used in industrial production processes like pick-and-place, logistics, and workstations, helping and optimizing the production workflows.

  • ZLP1.png

The collection of rosservices supplied by the package exposes the functionalities of the device, helping with the development of advanced applications in factories facilities, and motivating the ROS-Industrial community growth.

  • zlaser_applic.png

Getting started

Software architecture

The ZLP software has a modular architecture. These modules communicate via TCP/IP and have to be located within the same network.

  • architecture.png

Z-Laser offers different solutions depending on where you prefer to have zService running. This package has been developed in a device with zService built-in to the projector itself.

In this case, zService IP address is, on port 9090. In case you have zService running on your PC, contact z-laser to get the specific IP address of your device.

Projector is expected to be reachable under (factory default configuration).

To get more information about Thrift and zService, refer to ZLP1-quickstart-guide (provided by z-laser).

Reference coordinate systems

The laser projector ZLP1 covers working fields from 1.0m x 1.0m up to 3.5m x 3.5m; and working distances from 1.0m to 3.0m. It is able to project figures in a specific position at various workpiece distances. It also has the ability to move and rotate the displayed object. To do this, you need to specify a reference coordinate system first. In order to embrace this issue, the definition and setting up of reference coordinate systems will be further explained in this section.

There are two ways to specify a coordinate system: either by setting the coordinates manually, or by automatic target search. Note that each point on the projection surface can be referenced by two different coordinate systems:

  • Projector Reference System {P}. Specified in factory, the coordinate system origin is always the same and cannot be changed. User-defined reference systems have to be related to this.
  • User Reference System {T}. The user can set the coordinate system origin, its resolution and orientation. It must be related to {P}.

Note that a coordinate system needs 4 points to be fully defined.

  • projector_origin.png

Setting user-defined coordinate system manually

An example of manual system definition is going to be developed in order to guide this section. First, the user must decide the coordinate system’s resolution to set a position. See the differences in the scheme below. This value is non-dimensional, i.e., do not represent real world dimensions.

  • resolution.png

For the following example, we use a resolution of 1000. Then, the user should indicate the position of the four points that define the coordinate system in real world values (millimetres). This means to specify the desired correspondent points in Projector Reference System {P}. For example:

  • P1 = (-100, -100) [mm]

  • P2 = (-100, 100) [mm]

  • P3 = (100, 100) [mm]

  • P4 = (100, -100) [mm]

Please, be careful to indicate dimensions that correspond to either a square or a rectangle.

Finally, the user is required to introduce the value for T1 that will form the User Reference System {T}. Then, the following points will be auto-defined based on the resolution value. In case the above values represent a square as in the example, resolution is applied directly:

  • T1 = (0, 0)

  • T2 = (1000, 0)

  • T3 = (0, 1000)

  • T4 = (1000, 1000)

However, if it is a rectangle, resolution is applied to axis with the longest dimension and autoscaled for the other. When creating a coordinate system, those values are returned for the user to know.

This is a scheme of the example:

  • coord_sys.png

In the image above, the point Tx = (300, 300) referenced from User Reference System {T}, will be located on the real projection surface at Px = (-40mm, -40mm) from the origin of Projector Reference System {P}.

On the other hand, some situations may require a rotation of the reference system. To achieve that, the user should set the appropriate coordinates in Projector Reference System {P}. In the scheme below, note that User Reference System {T} remains the same with respect to the previous example, while Projector Reference System {P} changed to:

  • P1 = (0, -100) [mm]

  • P2 = (100, 0) [mm]

  • P3 = (0, 100) [mm]

  • P4 = (-100, 0) [mm]


Finally, notice that real world coordinates specified in Projector Reference System {P} depends on the projection distance (distance between the laser projector and the projection surface), as it is a beam.

In this example, the real distance between projector and surface is ‘d’. If it is incorrectly indicated as a greater distance ‘D’, the projected points would be located more distant (‘W’) to the coordinate system origin than the user has specified (‘w’).

  • distance.png

For that reason, the installation projection distance must be correctly indicated, and it can be calculated using the following formula: d = f * 0.5 / (tan(α/2)) where

  • d: is the projection distance in [mm]
  • f: longest side of the projection surface in [mm]
  • α: optical opening angle of value 56º.

For example:

Given a length of the desired projection area of 2000mm and an opening angle of 56o, it results in an installation distance of 1880.7mm:

  • angle.png

Licensing the projector

A license is always required to use the ZLP software. Please, contact your ZLaser supplier to get a valid license. Save the license file under <package_directory>/lic folder. Then, indicate the license file name on the config file config/communication_settings.yaml.


This package provides two ways of including ZLP1 into your application:

  • - Simply run node and interact with projector throughout ROS services interface:
     roslaunch z_laser_projector projector_zlp1.launch
    • Add arg load_user_coordinate_system:=true to load values from config/user_coordinate_system.yaml.

    - Or include the library into your application directly. Refer to class documentation:

     #!/usr/bin/env python3
     from z_laser_projector.zlp_projector_manager import ZLPProjectorManager
     from z_laser_projector.zlp_utils import CoordinateSystemParameters, ProjectionElementParameters

Code API

The zlp_projector_ros provides a collection of services in order to operate the projector device from ROS environment, as connecting, disconnecting, defining coordinate systems, starting and stopping projection, etc.


~add_line (z_laser_projector/Line)

  • Define a new polyline projection element related to the active coordinate system. It won't be visible until the projection is triggered.


~connect (std_srvs/Trigger)

  • Open connection with projector
~disconnect (std_srvs/Trigger)
  • Close connection with projector
~projection_start (std_srvs/Trigger)
  • Start projection of elements associated to the active coordinate system on the surface
~projection_stop (std_srvs/Trigger)
  • Stop projection of all elements
~define_coordinate_system (z_laser_projector/CoordinateSystem)
  • Define a new reference system with the given points coordinates manually by the user
~coordinate_system_list (z_laser_projector/CoordinateSystemList)
  • Get the list of defined coordinate systems
~set_coordinate_system (z_laser_projector/CoordinateSystemName)
  • Set the indicated coordinate system as active. The rest of defined systems remain in the background.
~remove_coordinate_system (z_laser_projector/CoordinateSystemName)
  • Remove the active coordinate system. Then, you should set another coordinate system.
~show_active_coordinate_system (z_laser_projector/CoordinateSystemName)
  • Project reference points, origin axes and frame of active coordinate system for user checking.
~hide_shape (z_laser_projector/ProjectionElement)
  • Hide projection element from active coordinate system
~unhide_shape (z_laser_projector/ProjectionElement)
  • Unhide projection element from active coordinate system
~remove_shape (z_laser_projector/ProjectionElement)
  • Remove projection element from active coordinate system


~projector_IP (string)

  • Projector IP address
~server_IP (string)
  • ZLP-Server IP address
~connection_port (int)
  • Connection port number
~license_file (string)
  • ZLP license file path
~coordinate_system_name (string, default: "default_cs")
  • Name of coordinate system
~coordinate_system_resolution (string, default: 1000)
  • Resolution of coordinate system
~coordinate_system_distance (string, default: 1500)
  • Distance between laser projector device and projection surface
~P_/x (float)
  • x-position of point P1, P2, P3 or P4 from projector reference system {P}
~P_/y (float)
  • y-position of point P1, P2, P3 or P4 from projector reference system {P}
~T1/x (float, default: 0)
  • x-position of point T1 from user reference system {T}
~T1/y (float, default: 0)
  • y-position of point T1 from user reference system {T}

Demonstration Video



Supported by ROSIN - ROS-Industrial Quality-Assured Robot Software Components.
More information:

EU Flag

This project has received funding from the European Union’s Horizon 2020
research and innovation programme under grant agreement No. 732287.

Wiki: z_laser_projector (last edited 2020-09-15 05:21:13 by Fada_Catec)