3.8.2 Examples

In this tutorial we show how pens and pen sets can be manipulated by creating some jobs programmatically to inspect the pen sets then in RAYGUIDE.

Creating the Project with Visual Studio

Create the project as described in the former chapters, e. g. in the "HelloWorld" tutorial; we name it "UsingPens" here. The skeletal structure is the same:

Program.cs: Skeletal structure

Copy

//-----------------------------------------------------------------------------
// This example shows how pens can be used to customize the process parameters
// of objects.
//-----------------------------------------------------------------------------

using GlmSharp;
using RAYLASE.Marker;
using RAYLASE.Marker.Common;
using RAYLASE.Marker.Job;
using RAYLASE.MarkerPlugin.JobElements;
using System;

namespace UsingPens
{
  class Program
  {
    static void Main( string[] args )
    {
      Console.WriteLine( "\n\nUsing pens sample" + "\n-----------------\n\n" );
      using ( MarkerAPI markerAPI = new MarkerAPI() )
      {
        // ...
      }
    }
  }
}

The complete project can be found in folder C:\Program Files\RAYLASE\RAYGUIDE\SDK\SampleCode\Tutorials\UsingPens\.

Creating a simple job

The first thing we need is a simple job to modify its pens and pen set and some job elements to be added later. Add the following code to the skeleton's using section:

Program.cs: Creating a simple job

Copy

// Create the job:
IJobManager jobManager = markerAPI.JobManager;
JobDefinition jobDefinition1 = jobManager.CreateNewJob( "Using pens 2" );

// Create some job elements and spread them over the workspace:

MarkableRectangle rectangle1 = new MarkableRectangle { Size = new dvec2( 50000, 30000 ) };
rectangle1.MoveTo( new dvec3( -50000, 0, 0 ) );

MarkableCircle circle1 = new MarkableCircle();
circle1.MoveTo( new dvec3( 0, 0, 0 ) );

MarkablePolygon polygon1 = new MarkablePolygon();
polygon1.MoveTo( new dvec3( 50000, 0, 0 ) );

MarkableSpiral spiral1 = new MarkableSpiral();
spiral1.MoveTo( new dvec3( 0, 50000, 0 ) );

Modifying the job's pen set

As said above already each job contains a pen set. This code adds a new pen to the pen set, modifies some pens, removes some other pens and assigns some pens to the objects. Finally the objects are added to the job and the job is saved as "UsingPens2.rg".

Program.cs: Creating a simple job

Copy

// The job contains the default pen set; all process parameters
// are null at this stage which means that default values are used:
PenSet penSet = jobDefinition1.PenSet;

// If necessary a new pen can be created and added to the pen set:
MarkerPen myPen = new MarkerPen();
myPen.MarkSpeed = 0.1; // mark speed is not null any longer => default value will be overwritten with 0.1
myPen.Name = "My pen";
int myPenNumber = penSet.PenMap.Count + 1; // this is a unique pen number only if the already available pens are in sequence
penSet.AddPen( myPenNumber, myPen ); // adding an already used pen number would replace the current pen

// Already available pens can be modified:
penSet.PenMap[2].MarkSpeed = 0.2;
penSet.PenMap[3].LaserPower = 0.9;
penSet.DefaultPenNumber = 3;

// Probably unused pens can be removed from the pen set:
penSet.RemovePen( 4 );
penSet.RemovePen( 5 );
penSet.RemovePen( 6 );
penSet.RemovePen( 7 );

// Assign the process parameters to the job elements in various ways using pens:
rectangle1.PenNumber = 2;
circle1.PenNumber = 4; // a pen number not available in the pen set results in an object pen
circle1.MarkerProfile.PenSet[4].MarkSpeed = 0.3;
polygon1.PenNumber = myPenNumber;
spiral1.PenNumber = penSet.DefaultPenNumber;

// Add the objects to the job finally:
jobDefinition1.AddJobElement( rectangle1 );
jobDefinition1.AddJobElement( circle1 );
jobDefinition1.AddJobElement( polygon1 );
jobDefinition1.AddJobElement( spiral1 );

// Save the job to be opened in RAYGUIDE:
string path = Environment.ExpandEnvironmentVariables( "%temp%" );
jobManager.SaveJob( jobDefinition1, $"{path}\\UsingPens2.rg" );

When loaded into RAYGUIDE the pen set looks like this:

The modified pen set

As expected our new pen "My pen" is added with pen number 9, the laser power of pen 3 is modified to 90 percent and the mark speed of pen 2 is set to 0.2 m/s.

When selecting the "Circle" object we can see that pen 4 is an object pen now because there is no pen 4 in the job's pen set:

The modified pen set of the "Circle" object

Creating a pen set from scratch

If not satisfied with the default pen set, you can create your own pen set. This is done by creating some new MarkerPen objects, creating a new PenSet object and adding the pens to the pen set. Finally the job's current pen set is to be overwritten by copying the new one to the old one:

Program.cs: Creating a new pen set

Copy

// Create a second new job with similar job elements:
JobDefinition jobDefinition2 = jobManager.CreateNewJob( "Using pens 3" );
MarkableRectangle rectangle2 = new MarkableRectangle { Size = new dvec2( 50000, 30000 ) };
rectangle2.MoveTo( new dvec3( -50000, 0, 0 ) );
MarkableCircle circle2 = new MarkableCircle();
circle2.MoveTo( new dvec3( 0, 0, 0 ) );
MarkablePolygon polygon2 = new MarkablePolygon();
polygon2.MoveTo( new dvec3( 50000, 0, 0 ) );
MarkableSpiral spiral2 = new MarkableSpiral();
spiral2.MoveTo( new dvec3( 0, 50000, 0 ) );

// Create a new pen set:
PenSet myFirstPenSet = new PenSet();
MarkerPen pen1 = new MarkerPen() { Name = "strong pen", LaserPower = 0.8, MarkSpeed = 0.4 };
MarkerPen pen2 = new MarkerPen() { Name = "weak pen", LaserPower = 0.2, };
myFirstPenSet.AddPen( 10, pen1 );
myFirstPenSet.AddPen( 12, pen2 );

// Assign the pen set to the job and the process parameters to the objects:
jobDefinition2.PenSet.CopyFrom( myFirstPenSet, true );
rectangle2.PenNumber = 10; // assign pen 1
circle2.PenNumber = 12;    // assign pen 2
polygon2.PenNumber = 14;   // pen number 14 not available => a new pen with number 14 and default values will be created


// Add the objects to the job finally:
jobDefinition2.AddJobElement( rectangle2 );
jobDefinition2.AddJobElement( circle2 );
jobDefinition2.AddJobElement( polygon2 );
jobDefinition2.AddJobElement( spiral2 ); // no pen assigned => a new pen with number 1 and default values will be created

// Save the job to be opened in RAYGUIDE:
jobManager.SaveJob( jobDefinition2, $"{ path}\\UsingPens3.rg" );

Now we see a pen set with the newly created pens 10 and 12. Since we assigned the not existing pen 14 to the rectangle a pen 14 with default values has been created. A pen 1 is always there because it is the default pen.

The new pen set

Merging pen sets

Pen sets cannot only be copied from one pen set to another but even merged. Here we merge our newly created pen set myFirstPenSet into the pen set of our first job jobDefinition1:

Program.cs: Merging a pen set

Copy

// Pen sets cannot only be copied [use CopyFrom()] but even merged:
penSet.MergeFrom( myFirstPenSet );

// Save a third job file based on jobDefinition1 and containing the merged pen set:
jobDefinition1.Label = "Using pens 4";
jobManager.SaveJob( jobDefinition1, $"{ path}\\UsingPens4.rg" );

The result is a pen set containing the pens of both:

The merged pen set

If myFirstPenSet contained a pen number already existing in the pen set the old pen would be overwritten.

Pens and inheritance

Of course not only pen sets can be copied but single pens as well. When copying a pen to another all values of the old pen will be overwritten; this is done with the method CopyFrom(MarkerPen). If some values in the pen are not set (i. e. the values are null), the default values will be used.

In difference to that there is the method InheritValuesFrom(MarkerPen); this method keeps the old values where the new pen has null values and changes only the ones where values are set.

In this example we create a new pen3, named "copied pen", but overwrite it completely with our old pen1. And we create another new pen4, defining only the Name as "inheritor pen" and setting the LaserPower to 60 percent; additionally we inherit the other values from our just copied pen3 which contains a mark speed now of 0.8 m/s:

Program.cs: Copying and inheriting pen values

Copy

// Pens can be copied to overwrite all old values:
MarkerPen pen3 = new MarkerPen() { LaserPower = 0.7, Name = "copied pen", MarkSpeed = 0.5, JumpSpeed = 0.1 };
pen3.CopyFrom( pen1 ); // all values will be overwritten to LaserPower=0.8, MarkSpeed=0.4, JumpSpeed=2, Name="strongPen"

// Pens can inherit values from another pen, preserving already defined values:
MarkerPen pen4 = new MarkerPen() { Name = "inheritor pen", LaserPower = 0.6 };
pen4.InheritValuesFrom( pen3 );
jobDefinition2.PenSet.AddPen( 16, pen3 );
jobDefinition2.PenSet.AddPen( 17, pen4 );

// Save a fourth job file based on jobdefinition2:
jobDefinition2.Label = "Using pens 5";
jobManager.SaveJob( jobDefinition2, $"{ path}\\UsingPens5.rg" );

Our pen3, added with pen number 16, is then a complete copy of pen1 (still pen number 10), even the name is the same. pen4 ("inheritor pen") has preserved the values we had set (laser power and name), and the other values are the same as of the "strong pen":

The modified pen set