Created Date: Feb 16, 2021 11:11
Last Modifed Date: Feb 19, 2021 10:31

This section guides you through the installation and basic setup of Harlequin Direct, so that you can process your first PDF and confirm it has been output correctly.

Installation

There is no separate installer for Harlequin Direct; to deploy everything required, extract the supplied zip/archive file into the directory of your choice.

If you are running Harlequin Direct on Windows, you must install the following Visual Studio redistributables:

  • Microsoft Visual C++ 2015-2019 Redistributable
  • Microsoft Visual C++ 2013 Redistributable

Due to the use of socket-based communication, Windows Firewall may block access to certain ports during running on Windows. Similarly, ensure that you set appropriate permissions in Linux.

Connecting to Harlequin Direct

To confirm that a connection can be established on Windows, launch Harlequin Direct as follows from a command prompt in the directory with HarlequinDirect.exe:

HarlequinDirect -port 9999

To confirm the same on Linux, launch Harlequin Direct from its directory at the console/terminal as follows:

./HarlequinDirect -port 9999

In both cases, you should see:

HarlequinDirect
Version 1.6.0.52
(C) 2020 Global Graphics Software Ltd

If port 9999 is not available, Harlequin Direct will exit and you will also see Socket connection failed. Please try other ports until you discover one that is free.


To try the connection on Windows, use a telnet client such as PuTTY to connect to localhost on port 9999.

To test the connection on Linux, use telnet from the command prompt as follows:

telnet localhost 9999

In both cases, you should see the following in your telnet prompt:

HARLEQUIN_DIRECT_READY

If you do not see this output, something is likely blocking your socket-based communication. On Windows, this is usually due to Windows Firewall settings; on Linux, ensure that you update your port permissions.

Once you can communicate with Harlequin Direct, you can shut it down remotely over telnet with the following command:

EXIT

If you drive Harlequin Direct from another machine, repeat these steps from that machine, replacing localhost with the IP address of the machine running Harlequin Direct, to confirm that the required connection across the network can be established.

Licensing

To do anything beyond confirming your connection, you require a Harlequin Direct license, which is a base-64 encoded string associated with your password.

If you do not have a license string and password, please contact your Global Graphics representative, as you can't proceed without them.

Plugins

For extensibility and scalability, Harlequin Direct uses a plugin-based pipeline architecture, where the specific plugins and the number of threads devoted to them can be configured as required. (The number of parallel RIPs are also configurable, as you will see in the next section.)

The available plugins you can select depends on your digital press workflow, but the following pipeline, which we use for the remainder of this guide, is always available:

Screening → Packing → Tiff Output

Each stage of the pipeline receives its work from the previous stage or from the RIP (in the case of the first stage) in a queue; completed work goes onto the queue for the next plugin (if there is one).

To achieve different pipeline configurations, see the next section for details.

Basic configuration

Harlequin Direct uses a JSON (JavaScript Object Notation) format configuration file, which allows you to exercise control over all aspects of the application. The file is organized as a single top-level object containing multiple "section" sub-objects. The sections contain the actual configuration options. The following table covers the basic settings you may wish to change. (For a full table of configuration options, see Advanced Usage.)

Value

Description

RIP

PSConfig

 

The PostScript config that the HHR Scalable RIP uses, which is in SW/TestConfig.

RipCount

The number of farm RIPs used.

Security

HDLicence

The license string.

System

CommandPort

The port that opens for clients to connect to Harlequin Direct.

Pipeline

Stages

A representation of the image pipeline to construct. It includes the plugin to load (which must include the .dll extension, even on Linux) and a thread count to assign (enclosed in square brackets). Each stage is separated by a pipe character "|". For example:

"Plugin1.dll"[1]|"Plugin2.dll"[1]

Note: Once Global Graphics engineers set this up, you can edit only the thread count.

Socket

CommandSocketPort

Harlequin Direct uses the specified port number to control the pipeline during a print run.

StatusSocketPortHarlequin Direct uses the specified port number to retrieve the status of the pipeline during a print run.

Screening

ScreeningDirectory

The directory that ScreenPro loads its screen set from (see the ScreenPro User Guide).

Format

TargetBpp

The target bits per pixels (bpp) for the output format.

You can specify the configuration file either when launching Harlequin Direct or when it is idle (that is, not processing any active jobs) through the API or socket interface. The former is covered in the next section; see Advanced Usage for details on the latter.

Once you launch Harlequin Direct, you can't change the command port.

In the next section, use the example JSON config ExampleHDConfig.json.

Processing your first PDF with Harlequin Direct

Before you start, ensure a PDF is available to process. In this example, we use the Harlequin Direct brochure from the Global Graphics website (saved as brochure.pdf in the same directory as the Harlequin Direct binary).

Edit ExampleHDConfig.json to include your license string as the value for HDLicence (instead of INSERT_LICENSE_HERE).

Launch Harlequin Direct with example config file

On Windows, launch requires the following at the Command Prompt in the directory containing the HarlequinDirect.exe binary:

HarlequinDirect.exe -C ExampleHDConfig.json

On Linux, launch requires the following at the console/terminal in the directory containing the HarlequinDirect binary:

./HarlequinDirect -C ExampleHDConfig.json

Note: Since a command port is already specified in the configuration file, there is no need to supply one with -port.

Connect using telnet and supply password

Connect over telnet like in the Getting Started section with PuTTY or via the telnet command on Windows or Linux, respectively.

You should see:

HARLEQUIN_DIRECT_READY

Now enter the following at the telnet prompt, replacing yourpasswordhere with your actual password:

SET_PASSWORD,yourpasswordhere

You should see:

SOCKET_RECEIVED
COMMAND_QUEUED,1,SET_PASSWORD,yourpasswordhere
COMMAND_EXECUTING,1
COMMAND_SUCCEEDED,1

Your Harlequin Direct window should still only be showing the following:

HarlequinDirect
Version 1.6.0.52
(C) 2020 Global Graphics Software Ltd

Starting a print run

All jobs processed by Harlequin Direct must take place within a “Print Run”.

In your telnet session, submit the following command:

START_PRINT_RUN

In the telnet window, you should see:

SOCKET_RECEIVED
COMMAND_QUEUED,2,START_PRINT_RUN
COMMAND_EXECUTING,2
COMMAND_SUCCEEDED,2

And in the Harlequin Direct window, you should see:

Awaiting Command socket connection : Port 9998
Command Socket connected!
Awaiting Status socket connection : Port 9997
Status Socket connected!
Waiting for ScreenPro Direct Password
ScreenPro Direct Password Set
Idle (Output released)
Starting scalable rip...
Initial RIP virtual memory: 5 MiB (4776 KiB) used, 59 MiB (60416 KiB) commit limit, 128 MiB (131072 KiB) reserved

This means that the RIP and the screening pipeline are ready for processing your PDF.

Submitting your PDF

With the Print Run now started, you can send your PDF by supplying the path to it in a SUBMIT_JOB command.

Please note that this path is relative to the working directory of the Harlequin Direct application, so you would need to have copied it to that machine (or made it available via a network share) if you are driving Harlequin Direct from a different one.

To submit the job, send the following in the telnet session:

SUBMIT_JOB,datasheet.pdf,1

You should see something similar to the following in the Harlequin Direct window:

Scalable RIP Accepted Job 1 On Thu Dec 10 17:51:04 2020
File: datasheet.pdf
Config: Direct_Default_CMYK
Priority: 0
Ripping file %C%GGS/HarlequinDirect_Windows_v1.5.0/datasheet.pdf as PDF.
Starting Job On Thu Dec 10 17:51:04 2020
Title: Not Available
Subject: Not Available
Author: Not Available
Creator: Adobe InDesign 15.0 (Macintosh)
Producer: Adobe PDF Library 15.0
CreationDate: D:20200409105057+01'00'
ModDate: D:20200409105058+01'00'
Trapped: False
Scalable RIP Metadata for Job 1
File: datasheet.pdf
Pages: 2
Chunk Size: 1
Scalable RIP Starting Job 1 On Thu Dec 10 17:51:04 2020
Total time: 0.028 seconds (00:00:00.028)
Job Completed: datasheet.pdf

Scalable RIP Job 1 rendered 2 pages of 2...
Scalable RIP Job 1 Schedule time: 0.498 seconds (00:00:00.498)
Scalable RIP Job 1 Active time: 0.290 seconds (00:00:00.290)
Scalable RIP Job 1 Elapsed time: 0.319 seconds (00:00:00.319)
Scalable RIP Job 1 Completed: datasheet.pdf

If you check the Harlequin Direct directory, there should now be eight TIF files (four separations for each of the two pages of the datasheet) named from JobId_1_ImageId_1_Plane_1.tif to JobId_1_ImageId_2_Plane_4.tif.

Stopping the Print Run

Ordinarily, you would likely send more PDFs through at this point, but we stop the Print Run here.

Type the following in the telnet session:

STOP_PRINT_RUN

You should see:

SOCKET_RECEIVED
COMMAND_QUEUED,4,STOP_PRINT_RUN
COMMAND_EXECUTING,4
COMMAND_SUCCEEDED,4

In the Harlequin Direct window, you will see something like:

Waiting for IDLE command
Run complete
Idle (Output released)
Average Throughput : 399.107624 MB/s

You can now send the EXIT command to shut down Harlequin Direct and disconnect.

If all is confirmed to be working as expected, there is no need to use socket-based communication to drive Harlequin Direct beyond this point. We recommend that you use the Harlequin Direct API instead, which is detailed later in this guide.