The CalculateLayoutOnRoll function is used to determine how to layout prints, signs, or other dimensional items on a Roll (of indefinite length). This is commonly used to determine the amount of roll material that will actually be required to produce the item.
While it is possible to calculate these manually, doing so was complex. The need for this calculation occurred often enough to warrant this specialized function.
See Also cfl_function_-_calculatelayoutonsheet and how-to_use_the_calculatelayoutonroll_function_for_layout_calculations.
Function Usage
Function | Returns… | ||
CalculateLayoutOnRoll(Variable, ItemHeight, …) | Returns True if the calculation performed without error. Returns False if an calculation error (e.g. Division by Zero) resulted. The error message is passed back as the last parameter. |
These are complex functions that perform many calculations and can return many different values from the calculation. If the calculation perform without any errors, the function returns True. If there are any errors (such as division by zero), the function returns False and the error message is returned as one of the variable properties.
Function Parameters
Many of the parameters have default values and are not required, but a comma is still required to keep the parameter position intact if any parameters later in the list are passed. The list of passed values follows:
Parameter | Default | Description | |||
OutputVariable | None, required | The name of the variable to which all of the values will be placed. All of the calculated variables described in the following section are written into the “property bag” for this variable. | |||
ItemHeight | None, required | The height of the page, print, or sign to be produced. | |||
ItemWidth | None, required | The width of the page, print, or sign to be produced. | |||
ItemQuantity | 1 | The quantity of the page, print, or sign to be produced. | |||
RollWidth | None, required | The height of the roll on which the item will be produced. | |||
GapHeight | 0 | The amount of empty space between adjacent items tiled across the height (length) of the roll. | |||
GapWidth | 0 | The amount of empty space between adjacent items tiled across the width of the roll. | |||
ItemMarginTop | 0 | The amount of blank space left on the top of each item (for bleed, border, pockets, etc). | |||
ItemMarginBottom | 0 | The amount of blank space left on the bottom of each item (for bleed, border, pockets, etc). | |||
ItemMarginLeft | 0 | The amount of blank space left on the left side of each item (for bleed, border, pockets, etc). | |||
ItemMarginRight | 0 | The amount of blank space left on the right side of each item (for bleed, border, pockets, etc). | |||
RollLeader | 0 | The amount of empty space between the start of the roll and the first item. This is usually material consumed in the loading and setup process. | |||
RollTrailer | 0 | The amount of empty space between the last item and the end of the roll. This is usually material consumed in the unloading process. | |||
RollMarginLeft | 0 | The amount of empty space between the left side of the roll and the first item. | |||
RollMarginRight | 0 | The minimum amount of empty space between the right of the roll and the last item. | |||
OverlapAmount | 0 | If the item must be paneled, the OverlapAmount indicates the amount of an item that is reprinted on the subsequent panels so it can be overlapped when assembled. | |||
CanRotate | True | If true, allows the item to be rotated 90 degrees if this results in a more optimized layout (less total material used). | |||
CanTile | True | If true, allows the item to be tiled on the material. | |||
AvoidPaneling | True | If true, the calculations will favor rotation to avoid paneling even if is results in additional sheet usage. |
The values calculated by the layout function will be written into the “property bag” for the variable specified as the first function parameter. These values can then be accessed by name using the GetVariablePropertyValue() or GetVariablePropertyText() function.
Variable Properties Set
The results of the calculation are stored as variable properties, which can be accessed by any other variables or in any CFL statement using the GetVariablePropertyValue(VariableName, “PropertyName”, DefaultValue) or
the GetVariablePropertyText(VariableName, “PropertyName”, DefaultValue) function.
Variable Property Name | Description | ||
LayoutHeight | Sets the Variable Property to the ItemWidth if the ideal layout rotates the item or the ItemHeight if the layout is not rotated. | ||
LayoutWidth | Sets the Variable Property to the ItemHeight if the ideal layout rotates the item or the ItemWidth if the layout is not rotated. | ||
PrintsHigh | Sets the Variable Property to the number of “rows” printed on the roll. Each row contains ItemsWide columns on it. | ||
PrintsWide | Sets the Variable Property to the number of items that can be placed width-wise on one sheet. Note: For paneled items, ItemsWide may be less than one. (e.g. 1/2 if the item is paneled across 2 pieces width-wise.) |
||
PanelsWide | Sets the Variable Property to the number of panels required. ```` Max(1, 1/ItemsWide) |
||
TotalProducedArea | Sets the Variable Property to the area of the items produced: ```` ItemQuantity * (ItemHeight * ItemWidth) |
||
TotalRollLength | Sets the Variable Property to the total roll length required to produce ItemQuantity items. | ||
TotalRollArea | Sets the Variable Property to the total area of the roll used. ```` TotalRollLength * RollHeight |
||
TotalScrapArea | Sets the Variable Property to the area of the scrap (unused material left over on the sheets). ```` TotalRollArea - TotalProducedArea |
||
IsRotated | Sets the Variable Property to True if the optimal layout (based on the parameters given) was achieved by rotating the item by 90 degrees. | ||
IsTiled | Sets the Variable Property to True if the optimal layout (based on the parameters given) allowed multiple items to be placed wide on a roll. | ||
IsPaneled | Sets the Variable Property to True if the optimal layout (based on the parameters given) required the item to be split across two or more rolls. | ||
ErrorMessage | If an error occurs during the calculation, the formula will sets the Variable Property to False and the error message will be returned here. When there is no error in the calculation, this will set the Variable Property to an empty (blank) string. |