This is an old revision of the document!
The CalculateLayoutOnSheet function is used determine how to layout prints, signs, or other dimensional items on a Sheet (of defined width and length). This is commonly used to determine the number of sheets 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_-_calculatelayoutonroll and how-to_use_the_calculatelayoutonsheet_function_for_layout_calculations.
Function Usage
Function | Returns… | ||
CalculateLayoutOnSheet( 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. | |||
DuplicateTwoSided | False | True is the page, print, or sign will be duplicated (identically) on both sides, in which case the number of prints, impressions, or faces will be double the item quantity. | |||
SheetHeight | None, required | The height of the sheet on which the item will be produced. | |||
SheetWidth | None, required | The height of the sheet on which the item will be produced. | |||
GapHeight | 0 | The amount of empty space between adjacent items tiled across the height of the sheet. | |||
GapWidth | 0 | The amount of empty space between adjacent items tiled across the width of the sheet. | |||
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). | |||
SheetMarginTop | 0 | The amount of empty space between the top of the sheet and the first item. | |||
SheetMarginBottom | 0 | The amount of empty space between the bottom of the sheet and the first item. | |||
SheetMarginLeft | 0 | The amount of empty space between the left side of the sheet and the first item. | |||
SheetMarginRight | 0 | The amount of empty space between the right side of the sheet and the first 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
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 items that can be placed height-wise on one sheet. Note: For paneled items, ItemsHigh may be less than one. (e.g. 1/3 if the item is paneled across 3 pieces height-wise.) |
||
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.) |
||
PrintsPerSheet | Sets the Variable Property to the number of items that can be placed on one sheet. ```` ItemsHigh * ItemsWide Note: For paneled items, ItemsPerSheet may be less than one. |
||
LayoutSheets | Sets the Variable Property to the number of sheets required to produce ItemQuantity items. ```` RoundUp( ItemQuantity / ItemsPerSheet ) |
||
TotalProducedArea | Sets the Variable Property to the area of the material for one side of the items produced: ```` ItemQuantity * (ItemHeight * ItemWidth) |
||
TotalProducedSurfaceArea | Sets the Variable Property to the surface area of all of the pages, prints, or signs produced. ```` ItemQuantity * (ItemHeight * ItemWidth) * (IF DuplicateTwoSided THEN 2 ELSE 1 ENDIF) |
||
TotalSheetArea | Sets the Variable Property to the area of all of the material (sheets) used. ```` LayoutSheets * (SheetHeight * SheetWidth) |
||
TotalScrapArea | Sets the Variable Property to the area of the scrap (unused material left over on the sheets). ```` TotalSheetArea - 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 on a single sheet. | ||
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 sheets. | ||
ErrorMessage | If an error occurs during the calculation, the formula will sets the specified VariableProperty reference to False and the error message will be returned here. When there is no error in the calculation, this will set the specified VariableProperty reference to an empty (blank) string. |