Units and formatting of output values

When generating the final text in the output of a Front-End program, it is important to take into account the format of the data received by the CNC machine tool. It should be borne in mind that Autodesk Inventor stores data in its own internal format. For example, all distance values are stored in cm and angle dimensions in radians. Therefore, when generating data in the Front-End program, it is important to convert the data into the required format. For example, in Europe many machines accept distances in metric, i.e. mm, while the USA uses the imperial system, i.e. inches. In addition, it may be important how many decimal places the system needs to declare. This can be three or decimal places, zeroes may be required in decimal places, decimals may be omitted, etc. For this formatting of output values, Woodwork for Inventor JS Macro and Post-processor APIs provide the possibility to describe the output formats and use them where needed in the program.

The format definitions area of the global section is used to define the formatting of codes output to the NC file. It consists of the format definitions (createFormat) as well as definitions that determine when the codes will be output or suppressed (createModal, createVariable, createReferenceVariable, createIncrementalVariable).

The createFormat command defines how codes are formatted before being output to the NC file. It can be used to create a complete format for an output code, including the letter prefix, or to create a primary format that is referenced with the output definitions. It has the following syntax.

createFormat({specifier:value, specifier:value, …});

The specifiers must be enclosed in braces ({}) and contain the specifier name followed by a colon (:) and then by a value. Multiple specifiers are separated by commas.

Specifier		Value
prefix		Defines the prefix of the output value as a text string. The prefix should only be defined if this is a standalone format and is not used for multiple output definitions.
suffix		Defines the suffix of the output value as a text string. The suffix should only be defined if this is a standalone format and is not used for multiple output definitions.
decimals		Defines the number digits to the right of the decimal point to output. The default is 6.
forceDecimal		When set to true the decimal point will always be included with the formatted number. false will remove the decimal point for integer values.
forceSign		When set to true will force the output of a plus (+) sign on positive numbers. The default is false.
width		Specifies the minimum width of the output string. If the formatted value's width is less than the width value, then the start of the number will either be filled with spaces or zeros depending on the value of zero-pad. If the format is used to output a code to the NC file be sure to set zero pad to true, otherwise the prefix and value could be separated by spaces. The width of the output string includes the decimal point when it is included in the number, but not the sign of the number. The default is 0.
zeropad		When set to true will fill the beginning of the output string with zeros to match the specified width. If width is not specified or the output string is longer than width, then no zeros will be added. The default is false.
trim		When set to true the trailing zeros will be trimmed from the right of the decimal point. The default is true.
trimLeadZero		When set to true will trim the lead zero from a floating-point number if the number is fractional, e.g. .123 instead of 0.123. The default is false.
scale	Defines a scale factor to multiply the value by prior to formatting it for output. scale can be a number or a number designator, such as “mm”,“cm”,“in”,“deg”. The default is 1.
offset	Defines a number to add to the value prior to formatting it for output. The default is 0.
separator	Defines the character to use as the decimal point. The default is '.'.

Once a format is created, it can be used to create a formatted text string of a value that matches the properties in the defined format. The following table describes the functions defined in the format object.

Function	Description
Output(value)	Returns the formatted text string representation of the number.

var xFormat = Utility.CreateFormat({decimals:3, trim:false, forceSign:true});

xFormat.Output(4.5); // returns "+4.500"

var yFormat = Utility.CreateFormat ({decimals:3, forceSign:true});

yFormat.Output (4.5); // returns "+4.5"

var toolFormat = Utility.CreateFormat ({prefix:"T", decimals:0, zeropad:true, width:2});

toolFormat.Output (7); // returns "T07"

var aFormat = Utility.CreateFormat ({decimals:3, forceSign:true, forceDecimal:true, scale:”DEG”});

aFormat.Output (Math.PI); // returns "+180."

var zFormat = Utility.CreateFormat ({decimals:4, scale:10000, forceDecimal:false});

zFormat.Output (1.23); // returns 12300 (leading zero suppression)

The format object is used to format values, but has no connection to the output of the variable, except for formatting a text string that could be output. It does not know what the last output variable is, which is important when you do not want to output a code if the value has not changed from its previous output value.

The createVariable, createModal, createReferenceVariable, and createIncrementalVariable functions create output objects that are used to control the output of a code. The createVariable and createModal objects are used to output codes/registers only when they change from the previous output value, the createReferenceVariable is used to output values when they are different from a specified reference value, and the createIncrementalVariable is used for the output of incremental values, i.e. the output value will be an incremental value based on the previous value and the input value.

The createVariable and createModal objects can be used interchangeably since they both output only the values that have changed. In a post-processor you will see that the createModal object is used for the output of G-code or M-code modal groups, where multiple codes can be output in a single block and will only be output when the code changes value from the previous code in this group. The createVariable object is used for all other code/register output such as the axes registers, spindle speed, feedrates, etc. The only difference in these objects the functions that belong to them, for example you can disable the output of a Variable, but not of a Modal.

You can use the createFormat object for codes/registers that should be output whenever they are encountered in the post, just be sure to add the prefix to the definition.

createVariable({specifier:value, specifier:value, …}, format);

createModal({specifier:value, specifier:value, …}, format);

createReferenceVariable({specifier:value, specifier:value, …}, format);

createIncrementalVariable({specifier:value, specifier:value, …}, format);

The specifiers must be enclosed in braces ({}) and contain the specifier name followed by a colon (:) and then by a value. Multiple specifiers are separated by commas. A format object is provided as the second parameter. Some of the specifiers are common to all three objects and some to a particular object, as listed in the following table.

Specifier	Object	Value
prefix	(all)	Text string that overrides the prefix defined in format.
force	(all)	When set to true forces the formatting of the value even if it does not change from the previous value. The default is false.
suffix	createModal	Text string that overrides the suffix defined in format.
first	createIncrementalVariable	Defines the initial value of an incremental variable. You will also have to call the variable.Format(first) function after creating the IncrementalVariable to properly store the initial value.

Once an output variable is created, it can be used to create a formatted text string for output. The following table describes the functions assigned to the output variable objects. The functions are properties of the defined variable object.

Function	Object	Description
Disable()	Variable ReferenceVariable IncrementalVariable	Disables this variable from being output. Will cause the return value from the format function to always be a blank string ("").
Enable()	Variable Reference Variable IncrementalVariable	Enables this variable for output. This is the default condition when the variable is created.
Format(value [,ref])	(all)	Returns the formatted text string representation of the number. Can return a blank string if the value is the same as the stored value in the Variable and Modal objects, the same as the reference value in the ReferenceVariable object, or generates a value of 0 in the IncrementalVariable object. The call to format for a ReferenceVariable object must contain the second ref parameter, which determines if the value should be formatted for output.
GetCurrent()	Variable Modal IncrementalVariable	Returns the value currently stored in this variable.
IsEnabled()	Variable ReferenceVariable IncrementalVariable	Returns true if this variable is enabled for output
Reset()	Variable Modal IncrementalVariable	Forces the output of the formatted text string on the next call to format, overriding the rules for not outputting a value.
SetPrefix(prefix-text)	(all)	Overrides the prefix of the variable.
SetSuffix(suffix-text)	Modal	Overrides the suffix of the variable.

var xyzFormat = Utility.CreateFormat({decimals:3, forceDecimal:true});

var xOutput = Utility.CreateVariable({prefix:"X"}, xyzFormat);

xOutput.Format(4.5); // returns "X4.5"

xOutput. Format (4.5); // returns "" (4.5 is currently stored in the xOutput variable)

xOutput.Reset(); // force xOuput on next formatting

xOutput.Format(4.5); // returns "X4.5"

xOutput.Disable(); // disable xOutput formatting

xOutput.Format(1.2); // returns "" since it is disabled

var gFormat = Utility.CreateFormat({prefix:"G", decimals:0, width:2, zeropad:true});

var gMotionModal = Utility.CreateModal({force:true}, gFormat);

gMotionModal.Format(0); // returns G00

gMotionModal.Format(0); // returns G00 (force is set to 'true')

gMotionModal.SetPrefix("G1=");

gMotionModal.SetSuffix("*");

gMotionModal.Format(1); // returns "G1=01*"

var iOutput =Utility.CreateReferenceVariable({prefix:"I", forceDecimal}, xyzFormat);

iOutput.Format(.001, 0); // returns "I0.001"

iOutput.Format(.0001, 0); // returns ""

var zOutput = Utility.CreateIncrementalVariable({prefix:"Z", first:.5}, xyzFormat);

zOutput.Format(.5); // after creating the IncrementalVariable you must call the format function

// with the same value as 'first' to properly set the initial value

zOutput.Format(1.2); // returns "Z0.7"

zOutput.Format(1.5); // returns "Z0.3"

zOutput.Format(1.5); // returns ""

zOutput.Format(0); // returns "Z-1.5"