Dimension

group Dimension

Core types for axes and coordinate spaces.

Dimension (abstract)

OCTypeID DimensionGetTypeID(void): Get the OCTypeID for the base Dimension class.

DimensionRef DimensionCreate(OCStringRef label, OCStringRef description, OCDictionaryRef metadata, OCStringRef *outError)

Create a basic Dimension instance.

Parameters:

label – Human-readable label for this dimension.
description – Optional description (can be NULL).
metadata – Optional application metadata dictionary (can be NULL).
outError – On failure, receives a descriptive OCStringRef.

Returns:

A new DimensionRef on success, NULL on failure.

OCStringRef DimensionCopyLabel(DimensionRef dim)

Retrieve a human-readable label for this dimension.

Parameters:

dim – The Dimension instance.

Returns:

Its label, or an empty string if unset.

bool DimensionSetLabel(DimensionRef dim, OCStringRef label, OCStringRef *outError)

Set or change this dimension’s label.

Parameters:

dim – The Dimension instance.
label – New label string.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

OCStringRef DimensionCopyDescription(DimensionRef dim)

Get the descriptive text for this dimension.

Parameters:

dim – The Dimension instance.

Returns:

Description string.

bool DimensionSetDescription(DimensionRef dim, OCStringRef desc, OCStringRef *outError)

Set or change this dimension’s description.

Parameters:

dim – The Dimension instance.
desc – New descriptive text.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

OCMutableDictionaryRef DimensionGetApplicationMetaData(DimensionRef dim)

Retrieve arbitrary metadata attached to this dimension.

Parameters:

dim – The Dimension instance.

Returns:

A shallow-deep‐copied OCDictionaryRef.

bool DimensionSetApplicationMetaData(DimensionRef dim, OCDictionaryRef dict, OCStringRef *outError)

Replace this dimension’s metadata.

Parameters:

dim – The Dimension instance.
dict – New metadata dictionary.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

LabeledDimension

OCTypeID LabeledDimensionGetTypeID(void): Get the OCTypeID for LabeledDimension.

LabeledDimensionRef LabeledDimensionCreate(OCStringRef label, OCStringRef description, OCDictionaryRef metadata, OCArrayRef coordinateLabels, OCStringRef *outError)

Create a custom LabeledDimension.

Parameters:

label – Name of the dimension.
description – Optional description.
metadata – Optional metadata dict.
coordinateLabels – Array of strings labeling each coordinate (≥2).
outError – On failure, receives a descriptive OCStringRef.

Returns:

New LabeledDimensionRef, or NULL.

LabeledDimensionRef LabeledDimensionCreateWithCoordinateLabels(OCArrayRef labels)

Create a LabeledDimension with only labels.

Parameters:

labels – Array of OCStringRef coordinate labels (≥2).

Returns:

New LabeledDimensionRef, or NULL.

OCArrayRef LabeledDimensionCopyCoordinateLabels(LabeledDimensionRef dim)

Get all coordinate labels.

Parameters:

dim – The LabeledDimension.

Returns:

OCArrayRef of OCStringRef.

bool LabeledDimensionSetCoordinateLabels(LabeledDimensionRef dim, OCArrayRef coordinateLabels, OCStringRef *outError)

Replace the set of coordinate labels.

Parameters:

dim – The LabeledDimension.
labels – New array of OCStringRef labels (≥2).
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

bool LabeledDimensionSetCoordinateLabelAtIndex(LabeledDimensionRef dim, OCIndex index, OCStringRef label)

Set the label at a specific index.

Parameters:

dim – The LabeledDimension.
index – Zero-based coordinate index.
label – New label string.

Returns:

true on success.

OCDictionaryRef LabeledDimensionCopyAsDictionary(LabeledDimensionRef dim): Dictionary serializer for LabeledDimension.

LabeledDimensionRef LabeledDimensionCreateFromDictionary(OCDictionaryRef dict, OCStringRef *outError): Recreate from a dictionary.

LabeledDimensionRef LabeledDimensionCreateFromJSON(cJSON *json, OCStringRef *outError): Recreate from JSON.

SIDimension

OCTypeID SIDimensionGetTypeID(void): Get the OCTypeID for SIDimension.

SIDimensionRef SIDimensionCreate(OCStringRef label, OCStringRef description, OCDictionaryRef metadata, OCStringRef quantityName, SIScalarRef offset, SIScalarRef origin, SIScalarRef period, dimensionScaling scaling, OCStringRef *outError)

Create an SI-quantitative dimension.

Parameters:

label – Name of the axis.
description – Optional description.
metadata – Optional metadata.
quantityName – Name of the physical quantity (e.g. “time”).
offset – Scale offset (SIScalarRef).
origin – Reference origin (SIScalarRef).
period – Period for wrapping (SIScalarRef).
scaling – dimensionScaling enum.
outError – On failure, receives a descriptive OCStringRef.

Returns:

New SIDimensionRef, or NULL.

SIDimensionRef SIDimensionCreateWithQuantity(OCStringRef quantityName, OCStringRef *outError)

Create an SI-quantitative dimension with only quantityName set; all other params default. label, description, metadata are NULL; offset, origin, period are NULL; periodic is false; scaling is kDimensionScalingNone.

Parameters:

quantityName – Name of the physical quantity (e.g. “time”).
outError – On failure, receives a descriptive OCStringRef.

Returns:

New SIDimensionRef, or NULL.

OCStringRef SIDimensionCopyQuantityName(SIDimensionRef dim): Get the physical quantity name.

bool SIDimensionSetQuantityName(SIDimensionRef dim, OCStringRef name, OCStringRef *outError)

Set the physical quantity name.

Parameters:

dim – The SIDimension.
name – New quantity name.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

SIScalarRef SIDimensionCopyCoordinatesOffset(SIDimensionRef dim): Get offset.

bool SIDimensionSetCoordinatesOffset(SIDimensionRef dim, SIScalarRef val, OCStringRef *outError)

Set offset.

Parameters:

dim – The SIDimension.
val – New offset scalar.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

SIScalarRef SIDimensionCopyOriginOffset(SIDimensionRef dim): Get origin.

bool SIDimensionSetOriginOffset(SIDimensionRef dim, SIScalarRef val, OCStringRef *outError)

Set origin.

Parameters:

dim – The SIDimension.
val – New origin scalar.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

SIScalarRef SIDimensionCopyPeriod(SIDimensionRef dim): Get period.

bool SIDimensionSetPeriod(SIDimensionRef dim, SIScalarRef val, OCStringRef *outError)

Set period.

Parameters:

dim – The SIDimension.
val – New period scalar.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

bool SIDimensionIsPeriodic(SIDimensionRef dim): Check if periodic.

bool SIDimensionSetScaling(SIDimensionRef dim, dimensionScaling scaling)

Set scaling type.

Parameters:

dim – The SIDimension.
scaling – New scaling enum.

Returns:

true on success.

OCDictionaryRef SIDimensionCopyAsDictionary(SIDimensionRef dim): Dictionary serializer for SIDimension.

SIDimensionRef SIDimensionCreateFromDictionary(OCDictionaryRef dict, OCStringRef *outError): Recreate from a dictionary.

SIDimensionRef SIDimensionCreateFromJSON(cJSON *json, OCStringRef *outError): Recreate from JSON.

SIDimensionRef SIDimensionCreateCopy(SIDimensionRef dim)

bool SIDimensionValidate(SIDimensionRef dim, OCStringRef *outError)

Validate an SIDimension instance for internal consistency.

Returns true if dim passes all of the same checks that SIDimensionCreate performs. On failure, returns false and (optionally) writes a human-readable error into *outErr.

Parameters:

dim – The SIDimension to check.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true if the dimension is valid.

SIMonotonicDimension

OCTypeID SIMonotonicDimensionGetTypeID(void): Get OCTypeID for SIMonotonicDimension.

SIMonotonicDimensionRef SIMonotonicDimensionCreate(OCStringRef label, OCStringRef description, OCDictionaryRef metadata, OCStringRef quantityName, SIScalarRef offset, SIScalarRef origin, SIScalarRef period, dimensionScaling scaling, OCArrayRef coordinates, SIDimensionRef reciprocal, OCStringRef *outError)

Create a monotonic (but not evenly-spaced) SI dimension.

Parameters:

label – Axis name.
description – Optional description.
metadata – Optional metadata.
quantityName – Physical quantity name.
offset – SIScalar offset.
origin – SIScalar origin.
period – SIScalar period.
scaling – dimensionScaling.
coordinates – Array of SIScalarRef at each grid point (≥2).
reciprocal – Reciprocal SIDimension (for FFT, etc).
outError – On failure, receives a descriptive OCStringRef.

Returns:

New SIMonotonicDimensionRef, or NULL.

SIMonotonicDimensionRef SIMonotonicDimensionCreateMinimal(OCStringRef quantityName, OCArrayRef coordinates, SIDimensionRef reciprocal, OCStringRef *outError)

Create a monotonic dimension with minimal parameters.

This is a convenience function that calls SIMonotonicDimensionCreate with sensible defaults for optional parameters:

label: NULL
description: NULL
metadata: NULL
offset: NULL (will be defaulted by the main function)
origin: NULL (will be defaulted by the main function)
period: NULL (will be defaulted by the main function)
scaling: kDimensionScalingNone

Parameters:

quantityName – Physical quantity name.
coordinates – Array of SIScalarRef at each grid point (≥2).
reciprocal – Reciprocal SIDimension (for FFT, etc), or NULL.
outError – On failure, receives a descriptive OCStringRef.

Returns:

New SIMonotonicDimensionRef, or NULL.

bool SIMonotonicDimensionSetCoordinates(SIMonotonicDimensionRef dim, OCArrayRef coords, OCStringRef *outError)

Replace the coordinate array.

Parameters:

dim – The SIMonotonicDimension.
coords – New array (≥2).

Returns:

true on success.

OCArrayRef SIMonotonicDimensionCopyCoordinates(SIMonotonicDimensionRef dim)

Create a copy of the coordinate array.

Parameters:

dim – The SIMonotonicDimension.

Returns:

OCMutableArrayRef containing SIScalarRef coordinates, or NULL on failure. Caller must release.

OCArrayRef SIMonotonicDimensionCreateAbsoluteCoordinates(SIMonotonicDimensionRef dim)

Create absolute coordinate array using CSDM convention.

Creates absolute coordinates using the formula: X^abs_k = X_k + o_k × 1

Where:

X_k = regular coordinates from SIMonotonicDimensionGetCoordinates()
o_k = origin_offset value

Parameters:

dim – The SIMonotonicDimension.

Returns:

OCArrayRef containing SIScalarRef absolute coordinates, or NULL on failure.

SIDimensionRef SIMonotonicDimensionCopyReciprocal(SIMonotonicDimensionRef dim): Get reciprocal dimension.

bool SIMonotonicDimensionSetReciprocal(SIMonotonicDimensionRef dim, SIDimensionRef rec, OCStringRef *outError)

Set reciprocal dimension.

Parameters:

dim – The SIMonotonicDimension.
rec – New reciprocal SIDimension.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

OCDictionaryRef SIMonotonicDimensionCopyAsDictionary(SIMonotonicDimensionRef dim): Dictionary serializer for SIMonotonicDimension.

SIMonotonicDimensionRef SIMonotonicDimensionCreateFromDictionary(OCDictionaryRef dict, OCStringRef *outError): Recreate from a dictionary.

SIMonotonicDimensionRef SIMonotonicDimensionCreateFromJSON(cJSON *json, OCStringRef *outError): Recreate from JSON.

SILinearDimension

OCTypeID SILinearDimensionGetTypeID(void): Get OCTypeID for SILinearDimension.

SILinearDimensionRef SILinearDimensionCreate(OCStringRef label, OCStringRef description, OCDictionaryRef metadata, OCStringRef quantityName, SIScalarRef offset, SIScalarRef origin, SIScalarRef period, dimensionScaling scaling, OCIndex count, SIScalarRef increment, bool fft, SIDimensionRef reciprocal, OCStringRef *outError)

Create an evenly-spaced SI dimension.

Parameters:

label – Axis name.
description – Optional description.
metadata – Optional metadata.
quantity – Physical quantity name.
offset – SIScalar offset.
origin – SIScalar origin.
period – SIScalar period.
scaling – dimensionScaling.
count – Number of points (≥2).
increment – SIScalar step between points.
fft – True if used for FFT.
reciprocal – Reciprocal dimension.
outError – On failure, receives a descriptive OCStringRef.

Returns:

New SILinearDimensionRef, or NULL.

SILinearDimensionRef SILinearDimensionCreateMinimal(OCStringRef quantityName, OCIndex count, SIScalarRef increment, SIDimensionRef reciprocal, OCStringRef *outError)

Create a minimal SILinearDimension with only quantity, increment, count, and reciprocal set. All other parameters are set to NULL, false, or kDimensionScalingNone.

Parameters:

quantityName – Physical quantity name.
count – Number of points (≥2).
increment – SIScalar step between points.
reciprocal – Reciprocal SIDimension.
outError – On failure, receives a descriptive OCStringRef.

Returns:

New SILinearDimensionRef, or NULL.

OCIndex SILinearDimensionGetCount(SILinearDimensionRef dim)

Get the total point count.

Parameters:

dim – The SILinearDimension.

Returns:

Point count.

bool SILinearDimensionSetCount(SILinearDimensionRef dim, OCIndex count)

Set the total point count.

Parameters:

dim – The SILinearDimension.
count – New point count (≥2).

Returns:

true on success.

SIScalarRef SILinearDimensionCopyIncrement(SILinearDimensionRef dim): Get the increment between points.

bool SILinearDimensionSetIncrement(SILinearDimensionRef dim, SIScalarRef inc)

Set the increment.

Parameters:

dim – The SILinearDimension.
inc – New increment scalar.

Returns:

true on success.

SIScalarRef SILinearDimensionCreateReciprocalIncrement(SILinearDimensionRef dim): Get reciprocal increment as SIScalar.

OCArrayRef SILinearDimensionCreateCoordinates(SILinearDimensionRef dim)

Create coordinate array following CSDM convention.

Creates coordinates using the formula: X_k = Δx_k × (J_k - Z_k) + b_k × 1

Where:

Δx_k = increment
b_k = coordinates_offset
J_k = [0, 1, 2, …, count-1] (index array)
Z_k = 0 if complex_fft is false, T_k/2 if complex_fft is true
T_k = count for even count, count-1 for odd count

Parameters:

dim – The SILinearDimension.

Returns:

OCArrayRef containing SIScalarRef coordinates, or NULL on failure.

OCArrayRef SILinearDimensionCreateAbsoluteCoordinates(SILinearDimensionRef dim)

Create absolute coordinate array using CSDM convention.

Creates absolute coordinates using the formula: X^abs_k = X_k + o_k × 1

Where:

X_k = regular coordinates from SILinearDimensionCreateCoordinates()
o_k = origin_offset value

Parameters:

dim – The SILinearDimension.

Returns:

OCArrayRef containing SIScalarRef absolute coordinates, or NULL on failure.

bool SILinearDimensionSetComplexFFT(SILinearDimensionRef dim, bool fft)

Mark/unmark FFT usage.

Parameters:

dim – The SILinearDimension.
fft – True to enable complex-FFT.

Returns:

true on success.

SIDimensionRef SILinearDimensionCopyReciprocal(SILinearDimensionRef dim): Get the reciprocal SIDimension.

bool SILinearDimensionSetReciprocal(SILinearDimensionRef dim, SIDimensionRef rec, OCStringRef *outError)

Set the reciprocal SIDimension.

Parameters:

dim – The SILinearDimension.
rec – New reciprocal SIDimension.
outError – On failure, receives a descriptive OCStringRef.

Returns:

true on success.

bool SILinearDimensionSetPeriodToWindow(SILinearDimensionRef dim): Set period to window size (increment × count).

bool SIDimensionSetPeriodToInfinity(SILinearDimensionRef dim): Set period to infinity (non-periodic).

OCDictionaryRef SILinearDimensionCopyAsDictionary(SILinearDimensionRef dim): Dictionary serializer for SILinearDimension.

SILinearDimensionRef SILinearDimensionCreateFromDictionary(OCDictionaryRef dict, OCStringRef *outError): Recreate from a dictionary.

SILinearDimensionRef SILinearDimensionCreateFromJSON(cJSON *json, OCStringRef *outError): Recreate from JSON.

Dimension Operations

bool SILinearDimensionMultiplyByScalar(SILinearDimensionRef dim, SIScalarRef scalar, OCStringRef *outError)

Multiply an SILinearDimension by a scalar, updating all dimension properties accordingly.

This operation scales the dimension’s increment, offset, origin, and period by the scalar, and updates the reciprocal dimension properties with the inverse scalar. The dimension is modified in-place.

Properties affected:

increment: Multiplied by the scalar
offset and origin: Multiplied by the scalar
period (if periodic): Multiplied by the scalar
quantityName: Updated based on the new unit
reciprocal (if exists): Multiplied by the inverse scalar

Parameters:

dim – The SILinearDimension to multiply (must be mutable)
scalar – The scalar to multiply by (cannot be zero)
outError – Optional error output parameter

Returns:

true if successful, false on error

bool SIMonotonicDimensionMultiplyByScalar(SIMonotonicDimensionRef dim, SIScalarRef scalar, OCStringRef *outError)

Multiply an SIMonotonicDimension by a scalar, updating all dimension properties accordingly.

This operation scales all coordinates, offset, origin, and period by the scalar, and updates the reciprocal dimension properties with the inverse scalar. The dimension is modified in-place.

Properties affected:

All coordinates: Each coordinate multiplied by the scalar
offset and origin: Multiplied by the scalar
period (if periodic): Multiplied by the scalar
quantityName: Updated based on the new unit
reciprocal (if exists): Multiplied by the inverse scalar

Parameters:

dim – The SIMonotonicDimension to multiply (must be mutable)
scalar – The scalar to multiply by (cannot be zero)
outError – Optional error output parameter

Returns:

true if successful, false on error

SIMonotonicDimensionRef SIMonotonicDimensionCreateByMultiplyingByScalar(SIMonotonicDimensionRef dim, SIScalarRef scalar, OCStringRef *outError)

Create a new SIMonotonicDimension by multiplying by a scalar.

This creates a copy of the original dimension with all coordinates and properties scaled by the scalar.

Create a new SIMonotonicDimension by multiplying by a scalar.

This operation scales all coordinates, offset, origin, and period by the scalar, and updates the reciprocal dimension properties with the inverse scalar.

Parameters:

dim – The SIMonotonicDimension to multiply
scalar – The scalar to multiply by (cannot be zero)
outError – Optional error output parameter
dim – The SIMonotonicDimension to multiply
scalar – The scalar to multiply by
outError – Optional error output parameter

Returns:

New SIMonotonicDimensionRef with scaled properties, or NULL on error

Returns:

A new SIMonotonicDimensionRef with scaled properties, or NULL on error

SILinearDimensionRef SILinearDimensionCreateByMultiplyingByScalar(SILinearDimensionRef dim, SIScalarRef scalar, OCStringRef *outError)

Create a new SILinearDimension by multiplying by a scalar.

Parameters:

dim – The SILinearDimension to multiply
scalar – The scalar to multiply by
outError – Optional error output parameter

Returns:

New SILinearDimensionRef with scaled properties, or NULL on error

SILinearDimensionRef SILinearDimensionCreateInverse(SILinearDimensionRef dim, OCStringRef *error)

Create an inverse SILinearDimension.

Parameters:

dim – The original SILinearDimension
error – Optional error output parameter

Returns:

New SILinearDimensionRef representing the inverse, or NULL on error

Typedefs

typedef enum dimensionScaling dimensionScaling

Enums

enum dimensionScaling

How to scale SI dimensions.

Values:

enumerator kDimensionScalingNone: No scaling applied.

enumerator kDimensionScalingNMR: NMR-specific scaling applied.

Functions

bool DimensionIsQuantitative(DimensionRef dim)

Determine whether a dimension represents quantitative or qualitative data.

Quantitative dimensions contain numeric, measurable data with physical units or mathematical relationships between data points. Qualitative dimensions contain categorical, discrete labels without inherent numeric meaning.

Classification Rules:

LabeledDimension: Always qualitative (false) - represents discrete categories
SIDimension: Always quantitative (true) - has physical units and scaling
SIMonotonicDimension: Always quantitative (true) - ordered numeric coordinates
SILinearDimension: Always quantitative (true) - evenly spaced numeric values
Base Dimension: Qualitative (false) - abstract placeholder

Parameters:

dim – The Dimension instance to classify.

Returns:

true if the dimension represents quantitative (numeric) data, false if qualitative (categorical) data or if dim is NULL.

OCDictionaryRef DimensionCopyAsDictionary(DimensionRef dim)

Serialize a Dimension (any subclass) to a dictionary.

Includes all base fields plus a “type” discriminator for dispatch.

Parameters:

dim – The Dimension instance.

Returns:

A new OCDictionaryRef, or NULL on error. Caller must release.

cJSON *DimensionCopyAsJSON(DimensionRef dim, bool typed, OCStringRef *outError)

Serialize a Dimension (any subclass) to JSON.

Includes all base fields plus a “type” discriminator for dispatch.

Parameters:

dim – The Dimension instance.
typed – Whether to include OCTypes metadata wrapping.
outError – On failure, receives a descriptive OCStringRef.

Returns:

A new cJSON object, or NULL on error. Caller must release with cJSON_Delete.

DimensionRef DimensionCreateFromDictionary(OCDictionaryRef dict, OCStringRef *outError)

Reconstruct a Dimension from a dictionary representation.

Dispatches to the correct subclass based on the “type” key, or falls back to the abstract base if missing.

Parameters:

dict – Source dictionary.
outError – On failure, receives a descriptive OCStringRef.

Returns:

New DimensionRef, or NULL on failure. Caller must release.

DimensionRef DimensionCreateFromJSON(cJSON *json, OCStringRef *outError)

Reconstruct a Dimension from a cJSON representation.

Delegates to DimensionCreateFromDictionary() after parsing.

Parameters:

json – Input cJSON object.
outError – On failure, receives a descriptive OCStringRef.

Returns:

New DimensionRef, or NULL on failure. Caller must release.

OCStringRef DimensionCreateAxisLabel(DimensionRef dim, OCIndex index)

Create a human-readable label for a specific coordinate index.

e.g. “Phase-3”, “Time-3/s”, “Frequency-5/Hz”

Parameters:

dim – The Dimension instance.
index – Zero-based coordinate index.

Returns:

New OCStringRef (caller must release), or NULL.