Unit Conversion
Introduction
The unit conversion feature of the CPT Tool allows you to define the unit of measurement used in storing, calculating and reporting data in the CPT Tool project database. In addition, the unit conversion feature can convert a project database from one particular set of units to another set of units.
The CPT Tool is designed to report data in the same unit it is stored in, this must be the case because doing large numbers of unit conversion calculations on reports would make report generation too slow for practical use.
By default, all derived parameter calculations is in SI units. Therefore, if the values required for the calculation are not in SI units, they will be converted to SI units for the calculation, and the results converted back to the target unit. For example, the CPT Tool calculation assumes Cone Resistance in MPa, and will convert the Cone Resistance value to MPa if it is stored in a different unit, such as tsf or kPa.
A list of available unit systems is stored in the DG_COM_UNIT_SYSTEM Library Lookup List. The current unit system is stored in the read-only Unit_System field in the CPT_PROJECT_PARAMETERS table.
The CPT Tool has two preconfigured unit systems that are ready to use. These are the SI and English unit systems. You may adjust these as required, or create a new unit system.
Three tutorials related to Units are included as appendices.
- Section Creating a New Unit System
- Section Entering a New Unit Quantity
- Section How to change a field unit and make it work with reports
Project Field Units
The unit of a field in the project database is determined by the value in the Units field property.
Library Configuration
The configuration tables reside in the gINT library file. It is crucial that these configuration tables exist and are configured for the CPT Tool to function correctly.
DG_COM_UNIT_CONVERSION
All units, conversion factors and equations are listed in this table.
Column Name | Description |
|---|---|
Source_Unit | Unit to be converted to base SI unit. The unit must exist in the gINT Field Units Library table. |
Formatted_Source_Unit | Formatted version of the unit for displaying on reports. If you wish to display text that is different to the source unit when presented on reports (such as apply a subscript or superscript to the unit), enter the text expression in this column. If blank, the Source_Unit value will be used to display units on reports. |
Source_To_SI_Conversion_Factor | Multiplier factor to convert the Source unit to the base SI unit. If the conversion cannot be represented by a factor, leave blank and enter an expression in the Source_To_SI_Conversion_Equation column. The conversion factor takes precedence over the conversion equation. The inverse of this value is used to convert a value that is in SI units to the Source unit. |
Source_To_SI_Conversion_Equation | Equation to convert the Source unit to the base SI unit. <<Source>> is a variable that represents the value that is to be converted, and must be included in the equation. The Source to SI Conversion Equation is only used if the Source to SI Conversion Factor cannot be retrieved. |
SI_Unit | The SI unit serves as the base unit for conversions, and acts as a bridge for converting one unit to another, by converting a source unit to the SI unit, and then converting the SI unit value to the target unit by applying the inverse of the factor or equation that converts the target unit to the SI unit. |
DG_CPT_FIELD_MAP
This table stores unit conversion related configuration specific for fields in the database.
The records in this table are not automatically ordered by Table_Name and Field_Name, so it is recommended that you maintain the order of the records manually in a logical/alphabetical order by right-clicking on a row header and selecting Insert Row, or by entering a new row at the bottom, then right-click + drag on the row header to change the row position.
Column Name | Description |
|---|---|
Table Name | Table Name |
Field Name | Field Name |
Location | Database location of the Table Field. The two options are Project and Library. However, unit conversion feature only applies to fields in the Project database. This is a required field. |
English | These columns store the unit for the table field. The name of the column represents the unit system. For example, SI stores the units for the SI unit system, and English stores the units for the English unit system, for the named field of the current row. The column names must be listed in the DG_COM_UNIT_SYSTEM library lookup list, as the column names are used as the unit system lookup values in the Unit Conversion Add-In and the DG_CPT_SYMBOLOGY_SCALES_UNITS table. |
English_FR_Minimum | Minimum value field rule property value to be applied to the current named field for the unit system. |
English_FR_Maximum | Maximum value field rule property value to be applied to the current named field for the unit system. |
English_FR_Decimals_Displayed | Decimals displayed field rule property value to be applied to the current named field for the unit system. |
English_FR_Round_To_Nearest | Round to Nearest field rule property value to be applied to the current named field for the unit system. |
English_FR_Format_Type | Format type field rule property value to be applied to the current named field for the unit system. Available options include Decimal Format, Scientific Notation, Significant Figures and BSI Moisture Content. |
English_Default | Default value field property value to be applied to the current named field for the unit system. |
DG_CPT_SYMBOLOGY_SCALES_UNITS
This table allows you to configure Log/Fence report column units, minimum/maximum scales and line divisions for each Unit System/Parameter combination, which will most likely differ between unit systems. The CPT Log/Fence report columns will automatically apply the report options depending on the current unit system.
The records in this table are not automatically ordered by Unit_System and Parameter, so it is recommended that you maintain the order of the records manually in logical/alphabetical order by right-clicking on a row header and selecting Insert Row, or by entering a new row at the bottom, then right-click + drag on the row header to change the row position.
Column Name | Description |
|---|---|
Unit System | Unit System |
Parameter | Parameter name |
Unit | Unit the parameter is in for the named unit system |
Unit Conversion of the Current Project
The Unit Conversion Add-In function is used to convert the current gINT project database from one unit system to another unit system, as configured in the library configuration tables. To open the Unit Conversion form, select Add-Ins > Datgel CPT Tool > Unit Conversion.
Current Unit System – Unit system of the project file
Convert To – Unit system to convert the current project file to
Validate – Runs a validation check on the unit conversion configuration for the unit system selected in the Convert To drop down list. The validation involves the following checks:
- Check all required configuration tables fields exist. This includes the Unit System, Field Rules and Default value fields in DG_CPT_FIELD_MAP, which are prefixed with the name of the unit system.
- Check the table/fields listed in DG_CPT_FIELD_MAP exist in the current project database.
- Check that for all table/fields that is to be converted from its current unit to a target unit, a conversion factor or equation can be determined. For example, if a particular field is in metres and the target unit for that field configured in DG_CPT_FIELD_MAP is kilograms, the conversion factor cannot be determined.
A log report will appear listing any failed validation checks. All validation errors must be corrected for the unit conversion to execute.
Execute – Runs a validation check, and then if successful, executes the unit conversion process based on the configuration for the unit system selected in the Convert To drop down list.
The unit conversion process is as below:
- The unit system selected in the Convert To drop down list is the Target unit system.
- The current unit for each field is taken from the Unit field property, and is taken as the Source unit.
- The value in the selected unit system column in DG_CPT_FIELD_MAP for the corresponding table/field as named in the Table_Name and Field_Name fields is taken as the Target unit.
- A unit conversion factor from the Source unit to the Target unit is determined from the DG_COM_UNIT_CONVERSION table. The conversion factor is determined by multiplying the factor to convert the Source unit to the base SI unit, then multiplying the inverse of the factor to convert the target unit to the base SI unit. The equation is used if the factor is missing.
- The values for the named fields in the current project database are multiplied by the conversion factor. If either the Source or Target unit is empty, then no conversion takes place for that field.
- The Target Unit, Field Rules and default values are applied to each table/field listed in DG_CPT_FIELD_MAP.
- The name of the target unit system is written to the Unit_System field on the CPT_PROJECT_PARAMETERS table.
If any errors are found in the validation check, the conversion will not be executed.
If the unit conversion is run on a gINT Project file (.gpj), a backup file will be made in the same directory before the unit conversion is applied. The file will be prefixed with a time stamp, and renamed to have an extension of (.dbk). If there are any errors that occur during the unit conversion process, or you wish to revert the changes made by the unit conversion, rename the *.dbk file to *.gpj.