X1 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:
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.
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.
Construction Line:
Same as the Line, but it is rendered as an “infinite” dotted line.
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.
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.
Set the
unit for your model (cm or mm):
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
Add
optional variables, in the same way as we did for required variables above.
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.
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.
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.
You can rename it as you want using only letters, digits, - and _.
Set the start point of the cut by editing the start tag.
Add new elements (line, circle, ellipse). Name your new elements and enter the formula for the end point of them:
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.
Repeat the step #3 until your cut is defined.
For
folds, bleeds, no_print_area do the same as we did for cuts.
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:
Repeat the first 6 steps from the
Creating a model section.
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
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.
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:
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:
Name
: unique identifier of the limit, usually used as an informative title
Error message
: the message displayed to the user
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:
Example | Name | Result |
$a && $b ($a and $b) | And | True, if both $a and $b are true |
$a || $b ($a or $b) | Or | True, if $a or $b is true |
! $a | Not | True if $a is not true |
$a xor $b | Xor | True if either $a or $b is true, but not both |
Comparison Operators:
$a == $b | Equal | True if $a is equal to $b after type juggling |
$a === $b | Identical | True if $a is equal to $b, and they are of the same type |
$a != $b | Not equal | True if $a is not equal to $b after type juggling |
$a !== $b | Not identical | True if $a is not equal to $b, or they are not of the same type |
$a < $b | Less than | True if $a is strictly less than $b |
$a > $b | Greater than | True if $a is strictly greater than $b |
$a <= $b | Less than or equal to | True if $a is less than or equal to $b |
$a >= $b | Greater than or equal to | True if $a is greater than or equal to $b |
Examples of limits: