ScaleUtilities 3.0.0

ScaleUtilities

A comprehensive .NET library for unit conversions across multiple scale types including Weight, Length, Volume, Temperature, Speed, Velocity, Angle, Voltage, Illuminance, Concentration, Volumetric Flow Rate, Time, Photosynthetically Active Radiation (PPFD), Global Horizontal Irradiance, Atmospheric Pressure, and Generic/standalone units. Features formula-based conversions using NCalc, extensive unit support, and validation utilities.

I. Overview

ScaleUtilities is a powerful .NET 9 library designed for converting values between units of the same measurement type. The library provides:

• 🔄 Universal Unit Conversion: Convert between units within the same scale type (e.g., kilograms to pounds, meters to feet)
• 📏 Scale Types Supported: Weight, Length, Volume, Temperature, Speed, Velocity, Angle, Voltage, Illuminance, Volumetric Flow Rate, Time, Photosynthetically Active Radiation (PPFD), Global Horizontal Irradiance, Atmospheric Pressure, Generic/standalone units (e.g. percentage), Wireless Signal Strength, Electrical Conductivity, and five dimension-specific concentration types (Mass/Volume, Mass/Mass, Volume/Volume, Molar, Parts-Per). The legacy combined Concentration type remains for backwards compatibility.
• 🧮 Formula-Based Conversions: Uses NCalc for mathematical expression evaluation, supporting complex conversion formulas
• ✅ Validation Tools: Built-in validation utilities to ensure unit and scale type combinations are valid
• 🎯 Type-Safe: Strongly typed with comprehensive C# models and enums
• ⚡ High Performance: Optimized conversion trees for fast lookups and calculations
• 🌐 Multi-Language Support: Conversion formulas available for C#, JavaScript, Python, Java, and TypeScript

Key Features

• Extensive Unit Support: Over 100+ units across all scale types
• International Standards: Follows SI, Imperial, US Customary, and specialized measurement systems
• Error Handling: Comprehensive exception handling with detailed error messages
• Async Support: Asynchronous methods for formula evaluation
• Documentation: Full XML documentation for IntelliSense support

II. Installation

From MyGet Feed

The ScaleUtilities library is available from our MyGet feed:

# Add the MyGet feed to your NuGet sources
dotnet nuget add source https://www.myget.org/F/cms-tool/api/v3/index.json -n "CMS Tools"

# Install the package
dotnet add package ScaleUtilities --version 1.0.1 --source "CMS Tools"

Or visit the MyGet package page directly: https://www.myget.org/feed/cms-tool/package/nuget/ScaleUtilities

Package Manager Console

Install-Package ScaleUtilities -Version 1.0.1 -Source "https://www.myget.org/F/cms-tool/api/v3/index.json"

PackageReference (csproj)

<PackageReference Include="ScaleUtilities" Version="1.0.1" />

III. Supported Types and Their Units

🏋️ Weight (25 units)

Metric Units: Microgram, Milligram, Centigram, Decigram, Gram, Decagram, Hectogram, Kilogram, Metric Ton, Quintal
Imperial/US: Ounce, Pound, Stone, Short Ton, Long Ton
Troy System: Troy Ounce, Troy Pound, Pennyweight
Apothecary: Grain, Dram, Apothecary Ounce
Specialty: Carat, Atomic Mass Unit

📏 Length (8 units)

Metric: Millimeter, Centimeter, Meter, Kilometer
Imperial: Inch, Foot, Yard, Mile

🫗 Volume (9 units)

Metric: Milliliter, Liter, Cubic Meter
US Customary: Fluid Ounce, Cup, Pint, Quart, Gallon

🌡️ Temperature (5 units)

Celsius, Fahrenheit, Kelvin, Rankine, Réaumur

🏃 Speed (11 units)

Metric: Meters/Second, Kilometers/Hour, Centimeters/Second, Millimeters/Second
Imperial: Miles/Hour, Feet/Second, Inches/Second, Yards/Second
Nautical: Knots
Scientific: Speed of Light, Mach

🎯 Velocity (11 units)

Same units as Speed with directional components

📐 Angle (11 units)

Standard: Degrees, Radians, Gradians
Subdivisions: Arc Minutes, Arc Seconds
Military: Mils, NATO Mils
Fractional: Turns, Right Angles
Historical: Compass Points, Binary Degrees

⚡ Voltage (10 units)

SI Units: Nanovolts, Microvolts, Millivolts, Volts, Kilovolts, Megavolts, Gigavolts
Electrical: Statvolts, Abvolts
Scientific: Planck Voltage

💡 Illuminance (9 units)

SI: Millilux, Lux, Kilolux, Lumen/Square Meter
Imperial: Foot-candle, Lumen/Square Foot, Lumen/Square Inch
CGS: Phot, Nox

⏱️ Time (12 units)

Sub-second: Nanoseconds, Microseconds, Milliseconds
Common: Seconds (base), Minutes, Hours, Days, Weeks
Calendar (averaged): Months, Years, Decades, Centuries

Calendar units use averaged lengths (Julian year = 365.25 days, month = year / 12) because the converter is stateless and has no calendar/date context. Sub-second and common units are exact.

☀️ Photosynthetically Active Radiation (4 units)

Photon Flux Density (PPFD, SI): Moles/m²/s, Millimoles/m²/s, Micromoles/m²/s (base), Nanomoles/m²/s

PAR is measured as Photosynthetic Photon Flux Density (PPFD) in µmol·m⁻²·s⁻¹. Only SI mole-prefix units are included, so every conversion is exact and assumption-free. Radiometric (W/m²) and photometric (lux) conversions are intentionally excluded because they are non-linear and depend on the light source's spectral distribution.

🔆 Global Horizontal Irradiance (7 units)

Metric (SI): Watts/m² (base), Kilowatts/m², Milliwatts/cm², Microwatts/cm² Solar: Calories/cm²/min, Langleys/min Imperial: BTU/(h·ft²)

GHI is the total shortwave solar power on a horizontal surface, measured as irradiance (power per area) in W·m⁻². Every factor is derived from exact defined constants (1 IT calorie = 4.1868 J, 1 IT BTU = 1055.05585262 J, 1 ft² = 0.09290304 m²), so all conversions are exact. PPFD (µmol·m⁻²·s⁻¹) and lux conversions are intentionally excluded because they are spectrum-dependent and non-linear.

🌡️ Atmospheric Pressure (10 units)

Metric (SI): Pascal (base), Hectopascal, Kilopascal, Megapascal, Bar, Millibar, Atmosphere, Millimetre of Mercury (mmHg) Imperial: Inch of Mercury (inHg), Pound per Square Inch (psi)

Atmospheric (barometric) pressure is force per unit area, measured in pascals. Every factor is derived from exact defined constants (1 atm = 101325 Pa, 1 bar = 100000 Pa, 1 conventional mmHg = 133.322387415 Pa, 1 inHg = 3386.389 Pa, 1 psi = 6894.757293168 Pa), so all conversions are exact. Gauge pressures (psig, barg) and pressure↔altitude/head-of-fluid conversions are intentionally excluded because they are not pure multiplicative factors.

🏷️ Generic / Standalone Units (1 unit)

Generic: Percentage (%)

Generic units are self-contained: each unit is a conversion island with an empty conversion tree. Only the identity conversion (same unit → same unit, value unchanged) succeeds; any attempt to convert a generic unit to a different unit throws, because generic units have no conversions. This is the right home for dimensionless quantities such as a bare percentage that shouldn't be converted to anything else.

🧪 Concentration

Concentration is split into dimension-specific scale types so that every conversion within a type is exact and requires no assumed density or molar mass. Units in different types are not mutually convertible, because bridging (e.g.) mass/mass to mass/volume would require a density the library deliberately refuses to assume.

• Mass/Volume Concentration (MassVolumeConcentration, pivot g/L): Kilograms/Cubic Meter, Grams/Liter, Milligrams/Liter, Micrograms/Liter, Grams/Cubic Meter, Milligrams/Cubic Meter, Pounds/Gallon, Ounces/Gallon, Grains/Gallon, Pounds/Cubic Foot, Percent Weight by Volume (% w/v)
• Mass/Mass Concentration (MassMassConcentration, pivot g/g): Grams/Gram, Milligrams/Gram, Micrograms/Gram, Nanograms/Gram, Grams/Kilogram, Milligrams/Kilogram (mg/kg), Micrograms/Kilogram, Nanograms/Kilogram, Percent by Weight (% w/w)
• Volume/Volume Concentration (VolumeVolumeConcentration, pivot L/L): Percent by Volume (% v/v), Per Mille by Volume (‰ v/v), Milliliters/Liter, Microliters/Liter, Liters/Cubic Meter, Milliliters/Cubic Meter
• Molar Concentration (MolarConcentration, pivot mol/L): Molar, Millimolar, Micromolar, Nanomolar
• Parts-Per Concentration (PartsPerConcentration, dimensionless): Parts per Million, Parts per Billion, Parts per Trillion

Deprecated: the original single Concentration type still exists for backwards compatibility. It interconverts all of the above via an assumed density (1 g/mL) and molar mass (1 g/mol). Prefer the dimension-specific types above for new code.

💧 Volumetric Flow Rate (15 units)

Metric - Milliliter: Milliliter/Second, Milliliter/Minute, Milliliter/Hour
Metric - Liter: Liter/Second, Liter/Minute, Liter/Hour
Metric - Cubic Meter: Cubic Meter/Second, Cubic Meter/Minute, Cubic Meter/Hour
US Customary - Fluid Ounce: Fluid Ounce/Second, Fluid Ounce/Minute, Fluid Ounce/Hour
US Customary - Gallon: Gallon/Second, Gallon/Minute (GPM), Gallon/Hour

Common Applications: HVAC systems, plumbing, irrigation, industrial pipelines, medical IV drips, fuel injection systems, water pumps, fire sprinkler systems

IV. Utility Methods

ScaleUnitValidationUtilities

Located in ScaleUtilities.Utilities namespace

Methods

Validate(ScaleUnit scaleUnit)

• Parameters: ScaleUnit scaleUnit - The ScaleUnit object to validate
• Return Type: void
• Exceptions:
  • ArgumentNullException - When scaleUnit is null
  • InvalidScaleUnitException - When the ScaleUnit has invalid type/code combination
• Description: Validates a ScaleUnit and throws an exception if invalid

IsValid(ScaleUnit scaleUnit)

• Parameters: ScaleUnit scaleUnit - The ScaleUnit object to check
• Return Type: bool
• Description: Returns true if the ScaleUnit has a valid type and code combination

IsValid(ScaleTypes type, string code)

• Parameters:
  • ScaleTypes type - The scale type enum
  • string code - The unit code to validate
• Return Type: bool
• Description: Returns true if the scale type and unit code combination is valid

Conversion Tree Utilities

Each scale type has its own conversion utility class:

WeightConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters:
  • decimal value - Value to convert
  • string sourceUnit - Source unit code (e.g., "KILOGRAM")
  • string targetUnit - Target unit code (e.g., "POUND")
• Return Type: decimal
• Description: Converts weight values between different units

LengthConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts length values between different units

VolumeConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts volume values between different units

TemperatureConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts temperature values between different units (handles offset-based conversions)

SpeedConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts speed values between different units

VelocityConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts velocity values between different units

AngleConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts angle values between different units

VoltageConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts voltage values between different units

IlluminanceConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts illuminance values between different units

ConcentrationConversionTreeUtilities (deprecated)

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts concentration values between different units using assumed density/molar mass. Kept for backwards compatibility — prefer the dimension-specific utilities below.

MassVolumeConcentrationConversionTreeUtilities / MassMassConcentrationConversionTreeUtilities / VolumeVolumeConcentrationConversionTreeUtilities / MolarConcentrationConversionTreeUtilities / PartsPerConcentrationConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts concentration values within a single physical dimension. Conversions stay within the group and require no assumed density or molar mass; cross-group conversions throw.

VolumetricFlowRateConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts volumetric flow rate values between different units (e.g., liters per second to gallons per minute)

PhotosyntheticallyActiveRadiationConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts Photosynthetically Active Radiation (PPFD) values between SI photon-flux-density units (e.g., micromoles per square metre per second to moles per square metre per second)

GlobalHorizontalIrradianceConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts Global Horizontal Irradiance (solar irradiance) values between power-per-area units (e.g., watts per square metre to kilowatts per square metre, langleys per minute, or BTU per hour per square foot)

AtmosphericPressureConversionTreeUtilities

Convert(decimal value, string sourceUnit, string targetUnit)

• Parameters: Same as WeightConversionTreeUtilities
• Return Type: decimal
• Description: Converts atmospheric (barometric) pressure values between force-per-area units (e.g., pascals to bar, atmospheres, millimetres of mercury, inches of mercury, or pounds per square inch)

Unit Code Constants

Each scale type provides constants for unit codes:

• WeightUnitCodes - All weight unit codes and validation methods
• LengthUnitCodes - All length unit codes
• VolumeUnitCodes - All volume unit codes
• TemperatureUnitCodes - All temperature unit codes and validation methods
• SpeedUnitCodes - All speed unit codes and validation methods
• VelocityUnitCodes - All velocity unit codes and validation methods
• AngleUnitCodes - All angle unit codes and validation methods
• VoltageUnitCodes - All voltage unit codes and validation methods
• IlluminanceUnitCodes - All illuminance unit codes and validation methods
• ConcentrationUnitCodes - All concentration unit codes and validation methods
• VolumetricFlowRateUnitCodes - All volumetric flow rate unit codes and symbol retrieval methods

Usage Examples

Basic Unit Conversion

using ScaleUtilities.Utilities;
using ScaleUtilities.Constants;

// Convert 1 kilogram to pounds
decimal result = WeightConversionTreeUtilities.Convert(1m, WeightUnitCodes.Kilogram, WeightUnitCodes.Pound);
// Result: 2.20462262184878

// Convert 100 degrees Celsius to Fahrenheit
decimal tempResult = TemperatureConversionTreeUtilities.Convert(100m, TemperatureUnitCodes.Celsius, TemperatureUnitCodes.Fahrenheit);
// Result: 212

// Convert 15.85 gallons per minute to liters per second
decimal flowResult = VolumetricFlowRateConversionTreeUtilities.Convert(15.85m, VolumetricFlowRateUnitCodes.GallonPerMinute, VolumetricFlowRateUnitCodes.LiterPerSecond);
// Result: 1.0 (approximately)

Unit Validation

using ScaleUtilities.Utilities;
using ScaleUtilities.Models;
using ScaleUtilities.Constants;

// Create a weight unit
var weightUnit = new WeightUnit(WeightUnitCodes.Kilogram);

// Validate the unit
bool isValid = ScaleUnitValidationUtilities.IsValid(weightUnit);
// Result: true

// Validate type/code combination
bool isValidCombo = ScaleUnitValidationUtilities.IsValid(ScaleTypes.Weight, WeightUnitCodes.Kilogram);
// Result: true

// Validate with exception throwing
try 
{
    ScaleUnitValidationUtilities.Validate(weightUnit);
    Console.WriteLine("Unit is valid!");
}
catch (InvalidScaleUnitException ex)
{
    Console.WriteLine($"Invalid unit: {ex.Message}");
}

Working with Unit Codes

using ScaleUtilities.Constants;

// Check if a unit code is valid
bool isValidWeight = WeightUnitCodes.IsValidWeightUnit("KILOGRAM");
// Result: true

// Get unit system category
string system = WeightUnitCodes.GetUnitSystem("KILOGRAM");
// Result: "Metric"

// Get all available units
string[] allWeightUnits = WeightUnitCodes.AllUnits;
// Result: Array of all weight unit codes

Volumetric Flow Rate Conversions

using ScaleUtilities.Utilities;
using ScaleUtilities.Constants;

// Convert water pump flow rate from liters per second to GPM
decimal pumpFlow = 5m; // 5 L/s
decimal gpm = VolumetricFlowRateConversionTreeUtilities.Convert(
    pumpFlow, 
    VolumetricFlowRateUnitCodes.LiterPerSecond, 
    VolumetricFlowRateUnitCodes.GallonPerMinute);
// Result: 79.25 GPM (approximately)

// Convert medical IV drip rate
decimal ivRate = 125m; // 125 mL/h
decimal mlPerMin = VolumetricFlowRateConversionTreeUtilities.Convert(
    ivRate,
    VolumetricFlowRateUnitCodes.MilliliterPerHour,
    VolumetricFlowRateUnitCodes.MilliliterPerMinute);
// Result: 2.083 mL/min (approximately)

// Get all available volumetric flow rate units
var availableUnits = VolumetricFlowRateConversionTreeUtilities.GetAvailableUnits();
// Returns array of VolumetricFlowRateUnit instances

// Get unit symbol
string symbol = VolumetricFlowRateUnitCodes.GetSymbol(VolumetricFlowRateUnitCodes.GallonPerMinute);
// Result: "gal/min"

Requirements

• .NET 9.0 or higher
• NCalc.NetCore 1.0.1 (automatically installed)

License

This library is licensed under the MIT License.

Support

For issues, questions, or contributions, please visit our GitLab repository: https://gitlab.com/iot93/back-end/commons/uom

© 2024 Linh Nguyen. All rights reserved.