X3 Advanced Details (EN only)

Packaging Editor

I. General description:

The main components of a model are:

Required:

The main variables of a model (e.g. Length, Width, Depth) which are used in frontend to rescale it. It may also have other important variables (e.g. Margin of the svg, Thickness of the 3D model etc.)

Optionals:

Other variables which help to create the model. They can hold numbers, formulas or other information needed. These variables can be split in 2 categories:

• normal: used for creating the model

• internal: used for features of the packaging system.

Sometimes, new variables can be defined here to help the process of creating the model. (e.g. a value/formula is used for x times, so it is stored in a variable)

Currently, the internal variables are:

• Show_Overall_Dimensions: shows/hides the values of the main variables of the model (length, width, depth)

• Show_Order_Number: shows/hides order number in the production PDF

• Order_Number: the order number in the production PDF

• Show_Bleed: shows/hides the bleed of the model

• Bleed_Outer_Stroke_Color: the color of bleed

• Bleed_Inner_Stroke_Color: sort of background color of the die-cut

• Bleed_Offset: the distance between the bleed and the die-cut

• Bleed_Width: The thickness of bleed

• Hide3D: used for hiding 2D elements in 3D model

• Show_Icc_Color: shows/hides CMYK colors

• Designer_Measurement_Width: Measurement of the model on the X-axis, used for designer

• Desinger_Measurement_Height: Measurement of the model on the Y-axis, used for designer

• In_Designer: shows/hides the measurement lines on the X and Y axis, used in designer

• Show_Trimbox_Dimensions: shows/hides trimbox of the model

• Reversed_Bleed: defines the direction of the bleed 

  • 0 - for counterclockwise bleed

  • 1 - for clockwise bleed

• Linked_3D_Model: the name used by the 3D soft in order to link to the 2D model (should be the same name as the model, without .json extension)

• Global_Trimbox: turn on/off the usage of trimbox inside Global Helpers

The values of the internal variables must not be changed, as it leads to behavior changes of the packing system in frontend. They can be modified inside the editor as long as they are not saved.

SvgWidth:

Here you can put the formula for the width of the model. If the field is left empty, the editor will automatically calculate the width based on the elements which compose the model.

SvgHeight:

Here you can put the formula for the height of the model. If the field is left empty, the editor will automatically calculate the width based on the elements which compose the model.

FormatWidth:

This is the formula which defines the width format used in frontend. It should be the width of the model (like SvgWidth but without the margin of the model). If the field is empty, it will automatically calculate it like this: SvgWidth - 2 * Margin, where Margin is the variable Margin (symbol M) of the model.

FormatHeight:

Same as FormatWidth, but the height instead.

Unit:

The unit used for the model. (mm or cm);

Limits:

Let say you want to prevent the frontend user to set the Width higher than the Length. You can do this by defining a Limit. All you need to do is to set the formula ($W <= $L) and the warning message “Width must be lower than Length”. In the frontend if the result of the formula ($W <= $L) is false then the warning message it’s displayed to the user.

Pages:

A model can have one or more pages. A page contains multiple entities:

• Offset: The offset is the origin of the page. This means that this point represents (0,0) in coordinates and all the points which are defined in the page are related to this.

• Cuts: contains all the cuts of the model. These are the blue lines in the svg. A cut is made of:

  • Start: defines a starting point of the cut (X and Y axis) relative to offset of the page

  • Lines: are defined only by the end point because the editor considers that the start point of a line is the end point of the previous element created (or the start point of the cut, if the current line is the first element in that cut)

  • Circles: defined same as lines, but has more properties to provide that are specific to circles

• Folds: contains all the folds of the model. They have the same properties as the cuts, but their color is red.

• Bleeds: contains the bleed of the model. They have the same properties as the cuts, but their color is green.

• No Print Area: contains the non printable areas of the model. They have the same properties as the cuts, but their color is green.

• Helpers: these are usually for internal usage. These implement the features of the packaging system and some are tied to the internal optional variables.

Global Helpers:

Like the Helpers of a page, these are for internal usage.

Commands:

A command is a feature of the system which helps the user in the process of creating a package. Their purpose is to automatize the calculation of mathematical formulas or to automatically calculate a result which would require a complex set of steps in order to get that result.

The commands make use of internal structures in order to create the desired effect:

Internal Structures:

1. Point:

It is represented by an ordered pair (x, y), as in Euclidean geometry. The x/y values can be filled with constants, variables of the model, or formulas.

1. Line (Segment):

It is defined by the starting point and the end point. It can be interpreted as a segment as well. In the editor, it is rendered as a dotted line between the 2 points.

1. Construction Line:

Same as the Line, but it is rendered as an “infinite” dotted line.

1. Circle:

It is defined by the center point and a radius.

A command has 2 elements:

• Name: a suggestive name for the command, which has to be unique among the other command names created in the editor

• Parameters: a list of specific parameters

Every command has a special parameter named Reference, which represents an ID. In order to use the result of a command, its reference ID must be used, like any other variable. Therefore, the value of this parameter must be unique among the other declared commands.

Usage of commands:

The commands are not bound to the elements defined in the Pages section. Instead, the Page entities make use of the commands in order to create the package by using their result through the Reference ID.

A command is declared beforehand and cannot use any entities created in the Pages section.

A command can use the variables declared in the Required and Optionals sections, or the result of any command created before it.

The elements constructed by a command (points, lines, arcs etc.) are not rendered in the final model. Therefore, in order to see any of these elements, the model in the editor must be rendered with the Additionals mode option checked.

The commands use the offset of the Page-1. Thus, every result is relative to this offset.

The commands usually return a result. This result could be a number or a container of more sub-results. For example, the reblend command returns 3 points and an angle.

In order to use the results of the container, you must use the Reference ID of the command and then append a dot (.) and the name of the sub-result you are interested in. The general schema to get a sub-result in a container is:

$[Reference_ID_command].[sub_result_1].[sub_result_1_1].[sub_result_1_1_1]...

Let’s say you have a command with its Reference ID set to FooBarCommand. Also, let’s suppose that this command returns a container of more sub-results: a point named fooPoint and a line named barLine. In order to access the X coordinate of the resulting point, we would use: $FooBarCommand.fooPoint.x.

Note: the X and Y Axis lines of the Cartesian coordinate system are predefined and you can use them. Their Reference ID is $ox for X Axis, and $oy for Y Axis.

Some of the commands available in the editor are:

addVariable:

Creates a variable, similar to those defined in Optionals section.

Parameters:

- Value: constants, variables of formulas

point:

Defines an instance of Point structure.

Parameters:

- X: the value for X Axis: constants, variables of formulas

- Y: the value for Y Axis: constants, variables of formulas

Return value: instance of Point

Accessible sub-results:

- x: the value set for the X field

- y: the value for the Y field

Example: $fooPoint.x

pointDistance:

Computes the Euclidean distance between 2 points.

Parameters:

- Point 1: ID of first Point

- Point 2: ID of second Point

Return value: an integer/float value

line:

Creates an instance of Line.

Parameters:

- Start Point: ID of the start point (must be instance of Point structure)

• End Point:

ID of the end point  (must be instance of Point structure)

Return value: instance of Line internal structure

Accessible sub-results:

- point: the value set for the first point (instance of Point)

- point2: the value set for the second point (instance of Point)

Example: $barLine.point

circleRadius:

Creates an instance of Circle structure.

Parameters:

- Center Point: ID of the center point (must be an instance of Point structure)

• Radius:

the radius of the resulting circle (int | float)

Return value: instance of Circle

Accessible sub-results:

- center: the value set for the Center Point field (instance of Point)

• radius:

the value set for the Radius field (int|float)

Example: $fooCircle.center

linesAngle:

Computes the angle between 2 lines in radians. (if intersection exists)

Parameters:

• First Line:

ID of the first line

• Second Line:

ID of the second line

Return Value: the angle between the 2 lines. (radians)

linePointAngleDistance:

Given the starting point, it creates the ending point of the line at a given distance and angle, returning a line defined by those points.

Parameters:

• Point:

ID of the starting point

• Angle:

angle of the resulting line relative to the X Axis. (in radians)

• Distance:

the distance between the starting and ending point (int | float)

Return value: instance of Line

bisector:

Returns the bisector of the acute angle of 2 lines.

Parameters:

• Line:

ID of the first line

• Line:

ID of the second line

Return value: instance of Line, representing the bisector

con:

Returns a construction line created by offsetting another given line.

Parameters:

• Line:

ID of the line

• Offset:

the offset of the resulting line (int | float)

Return value: instance of Line

rotateLine:

Returns a line rotated by a given angle and point.

Parameters:

• Line:

ID of the line

• Point:

ID of the pivot point by which the rotations is done

• Angle:

the angle in radians

Return value: the instance of the line given as parameter, but rotated.

INTER:

Returns the intersection point of 2 lines.

Parameters:

• Line 1:

ID of the first line

• Line 2:

ID of the second line

Return value: instance of Point

circleLineInter:

Returns the intersection point of a given circle and line.

Parameters:

• Circle:

ID of the circle (must be a Circle internal structure)

• Line:

ID of the line

• Intersection Point:

the intersection point which should be returned by the command (if the line is tangent to the circle, there is only one intersection point, thus any value of the parameter returns that point)

Return value: instance of Point

REBLEND:

Creates a smooth transition at the intersection of 2 lines. It creates an arc with a given radius in such a way that the 2 lines are tangent to the arc.

Parameters:

- Line 1: ID of the first line

- Line 2: ID of the second line

- Reblend Radius: the radius for the arc (float)

Return value: container of more sub-results

Accessible sub-results:

- center: the point representing the center of the reblend arc (instance of Point)

- firstPoint: one of the points at the extremities of the reblend arc (instance of Point)

- secondPoint: one of the points at the extremities of the reblend arc (instance of Point)

- angle: the angle of the reblend arc (in radians)

Example: $reblend.center | $reblend.angle

BLEND3:

Creates a smooth transition at the intersection of 3 lines by creating an arc in such a way that the 3 lines are tangent to the arc.

Parameters:

- Line 1: ID of the first line

- Line 2: ID of the second line

- Line 3: ID of the third line

Result value: container of more sub-results

Accessible sub-results:

- center: the point representing the center of the reblend arc (instance of Point)

- firstPoint: one of the points at the extremities of the reblend arc (instance of Point)

- secondPoint: one of the points at the extremities of the reblend arc (instance of Point)

- radius: the radius of the reblend arc (int | float)

Example: $blend3.firstPoint | $reblend.radius

Helper Functions:

A function performs a task for a given input (list of arguments) and returns an output based on the computations made on the input.

There are several functions defined in the editor which can be used as helping tools when creating a model. These functions can be used to compute mathematical results or shortcuts to ease the process of creating the model.

Usage:

A function will be called inside a formula, which then will return the result that will be used further by the system. This means that it can be used inside variables, commands, limits etc.

Example of a call: [name_of_function](arg1, arg2, …, argN), where

• name of function: the name of the function intended to be used

• arg1, arg2, …, argN: list of the parameters/arguments, which depends on the function called

In the following section describing the functions, we will consider that an expression means a combination/sequence of constants, variables, functions and operators that is evaluated by the system and a result is returned, considered as a value. Therefore, in the end, an expression will be computed as a value.

Available functions:

step:

Input: expression, value_1, test_value_1, value_2, test_value_2, … value_n, test_value_n, [else_value]

Where n is an arbitrary number, else_value is an optional argument as an expression

Description: Used when we want to check that a value is part of a given range of values. The function will check, from left to right, if the first argument’s value is strictly smaller than a test_value_i (using the operator <) from a list of pairs given as arguments. When the first check holds true, then it will return value_i as a result and it will stop the execution of the function. Optionally, a final else_value can be provided at the end, which will be returned if none of the tests give True.

Output: 

- value_i, where i is the index of the first test_value_i check is true

else_value (if provided), if none of the above is true

Example:

step($Thickness, 1, 0.5, 2, 1, 3, 2.5, 5)

Returns: 1, if $Thickness < 0.5, 2, if $Thickness < 1, 3 if $Thickness < 2.5, or 5 otherwise

stepUp:

Description: Same as step, but the check is being made using <= operator

eCase: 

Input: value_1, test_1, value_2, test_2, …, value_n, test_n, else_case,

where n is an arbitrary number and else_case is an expression.

Description: Implements if-else case, returns different results depending on which case is chosen (“true”). The arguments consists of one or more pairs of (value, test), and a final else_case value, which are used like this:

value: any expression

test: any expression that returns a Boolean value (True/False)

The pairs are evaluated from left to right. The first test that returns True will stop the checks, and will return the value.

Output: 

value_i, where i is the index of the first test_i that is true

else_case, if none of the above

Example:

eCase(10, $Thickness < 1, 15, $Thickness == 1.5, 20, $Thickness <= 3, 50)

Returns: 10 if $Thickness < 1, 15 if $Thickness == 1.5, 20 if $Thickness <= 3 or 50 otherwise

eMinMax: 

Input: value_to_check, min, max

Description: Checks if the first argument is in the interval/range [min, max] values. If so, it returns it, otherwise it returns min or max, depending if the argument is smaller than min or bigger than max.

Output: 

• value_to_check, if value_to_check is bigger than or equal to min and smaller than or equal to max

• min, if value_to_check is smaller than min

• max, if value_to_check is bigger than max

Example:

eMinMax($L + $W, 0.5, 3)

Returns: 

• $L + $W, if $L + $W >= 0.5 and $L + $W <= 3

• 0.5, if $L + $W < 0.5

• 3, if $L + $W > 3

round:

Input: expression, [precision = 0]

Description: rounds the value given at a precision

Output: the rounded value

ceil:

Input: expression

Description: round fractions up, rounded to the next highest integer

Output: rounded expression

floor:

Input: expression

Description: Round fractions down, rounded to the next lowest integer

Output: rounded expression

eRound:

Input: expression, nearest

Description: Rounds value/nearest to 0, then multiplies by nearest

Output: result of the above formula

Example:

eRound(10.7, 2)

Returns: 10

eRoundDown:

Input: expression, precision

Description: rounds value down by computing: floor(expression/precision) * precision

and taking the integer value of this (like applying a floor on the result)

If precision is 0, it will return floor(expression)

Output: result from the above

eRoundUp:

Input: expression, precision

Description: rounds value up by computing: ceil(expression/precision) * precision

If the precision is 0, it will return ceil(expression)

Output: result from the above

eTrunc:

Input: expression, precision

Description: Truncates the value of the argument to the precision

Output: truncated expression

cos, sin, tan:

Input: expression in radians

Description: computes the cosine/sine/tangent of the expression

Output: cosine/sine/tangent of the expression

asin, acos, atan:

Input: expression

Description: computes the arc cosine/sine/tangent of the expression

Output: arc cosine/sine/tangent of the expression

deg2rad:

Input: value

Description: Converts the value in degrees to the radian equivalent

Output: value in radian

rad2deg:

Input: expression

Description: Converts the radian value to the equivalent value in degrees

Output: value in degrees

min, max:

Input: value_1, value_2, …, value_n

Description: Computes the minimum/maximum value of the given arguments

Output: minimum/maximum value from the argument list

sqrt:

Input: expression

Description: Computes the square root of the argument

Output: square root of expression

abs:

Input: expression

Description: Computes the absolute value of the argument

Output: absolute value of expression

pow:

Input: expression

Description: Computes the exponential expression of the argument

Output: Exponential expression of expression

intval:

Input: expression

Description: Computes the integer value of the argument

Output: integer value of expression

getSign:

Input: expression

Description: Computes the sign of the argument

Output:

1:  value is positive (>= 0)

-1: value is negative (< 0)

getIntersectLineLine:

Input: point_1_x, point_1_y, point_2_x, point_2_y, point_3_x, point_3_y, point_4_x, point_4_y

Description: Computes the intersection point of the 2 lines (if it exists): (point_1_x, point_1_y, point_2_x, point_2_y) and (point_3_x, point_3_y, point_4_x, point_4_y)

Output: container with 2 values: intersection_point_x, intersection_point_y

Accessible by $result[0] and $result[1]

getIntersectLineCircle:

Input: point_1_x, point_1_y, point_2_x, point_2_y, arc_radius, arc_center_x, arc_center_y

Description: Computes the intersection point(s) of the line and the circle/arc (if exists)

Output: container with 2 values:

• 0: first point of intersection:

$result[0][‘x’], $result[0][‘y’]

• 1: second point of intersection:

$result[1][‘x’], $result[1][‘y’]

getLineLineAngle:

Input: point_1_x, point_1_y, point_2_x, point_2_y, point_3_x, point_3_y, point_4_x, point_4_y

Description: Computes the small angle (<=90) between 2 lines

Output: angle in radians

eUnits:

Input: unit, result_M, result_I

Unit: string value, can be ‘M’ (for metric system) or ‘I’ (for imperial system)

Description: Returns the value result_M or result_I depending on the unit argument

Output: the corresponding value to the unit selected

II. Creating a model

For a better understanding of the creation of the model, we will show you how a basic model can be implemented - a rectangular which has Length and Width as required variables.

1. By default, when you open the editor, there is already a

default model which has all the components predefined. Name the new model and press Save As to create it.

1. Set the

unit for your model (cm or mm):

1. Add required variables:

Length and Width

, 

where:

• Symbol represent the variable placeholder, which will be used later in formulas with the $ sign in front($L, $W).

• Value - default value of this variable

• Min - minimum value for this variable which can be set up by the frontend user

• Max - maximum value which can be set up by the frontend user

1. Add

optional variables, in the same way as we did for required variables above.

1. Set the formulas for

svgWidth and svgHeight to define how big is the model:

In our case svgWidth is 2 * Margin(left and right) + Length;  SvgHeigth is defined in the same way.

1. Open

Pages->page-1->offset and set the offset desired for the model.

In our case the origin of the page is the point ($M,$M) where $M is the Margin variable.

1. Now it’s the moment when you can define the cuts of the page. 

By default the model has an empty cut named cut-1. 

1. You can rename it as you want using only letters, digits, - and _.

2. Set the start point of the cut by editing the start tag.

3. Add new elements (line, circle, ellipse). Name your new elements  and enter the formula for the end point of them:

4. as you can see in the formula for line-2 we have [line-1.x] and [line-1.y]. This means you don’t have to repeat the formula, but to use an existing one. In our case the formula from line-1. This is useful when you have big formulas.

5. Repeat the step #3 until your cut is defined.

1. For

folds, bleeds, no_print_area do the same  as we did for cuts.

1. Press

Render Model every time you want to see the changes you made to your model.

10. When you want to save your model press:

• “Save” to save the model in the current file(displayed in the model input from top of the page) ,

• “Save as” to save your model in a new file.

III. Creating a model using commands (optional)

Let’s say we want to create a blend at one of the corners of this rectangle. We can use the commands to make it (it would make it faster if the angle between the 2 lines would be different than 90 degrees). We want to use the REBLEND command for this. Here are the steps:

1. Repeat the first 6 steps from the

Creating a model section.

1. Define the lines:

We need 2 lines for the REBLEND command. We start by defining each point of each line: PointA, PointB, PointC

Now, the lines: Line1, Line2

1. Define the reblend using the command:

If we render the model with the Additionals mode checked, we will get this:

We can only see the 3 points defined, PA, PB, PC. The reblend command does not render any elements, it just stores them. You have to manually render them if you want to see the result.

1. Recreate the rectangular shape, but with the blend.

When we add the cuts, we insert a circle for the reblend. In our case, we want the circle to be inserted in the upper left corner, right at the start.

We need to change the start of cut-1 from (0, 0) to one of the points resulted from the reblend command. (because the reblend command returns 2 points - the start/end points of the reblend arc)

I choose to set the start from the second point of the reblend as I will create the rest of the cuts in a clockwise way.

Then, we create the circle using the reblend stored variables for the center of the circle and the angle. The radius should be the same as the one inserted in the reblend command.

If we render the model up to this, we can see the the circle:

1. Repeat the remaining steps:

Now, we continue to create the rest of the model the same way we did before. In the end, we get this:

IV. Custom limits of a Model

Sometimes, min/max limits of a main variable are not enough for the model, thus more complex limits are required. We can validate different requirements of a model (e.g. “Length” must be higher than “Width”) and set a custom error message which is returned to the user when one of the rules is violated. The “custom limits” section of the model is found under the name of “limits” inside the model.

Structure of a custom limit:

1. Name

: unique identifier of the limit, usually used as an informative title

1. Error message

: the message displayed to the user

1. Formula

: logical/boolean expression which is evaluated, having the result:

- 0 (false): the validations fails, and the error message is returned to the user

- 1 (true): the validation is successful

The expression is like a normal formula, can contain references to variables of the model (e.g. $L, $W), operators, constants etc.

Examples of operators:

Logical operators:

Comparison Operators:

Examples of limits: