Interface GeometricInstanceConverterInterface

The GeometricInstanceConverterInterface interface is used to get, from a list of geometric instance ids, the corresponding part instance ids.

Such a conversion is dependant on a filtering context. Indeed, the list of current part instances is dependant on the chosen configuration (at least) and may be dependant on the list of visible part instances for example. For this reason, converting geometric instance ids (from a picking request for example) needs a filtering context (see VisibilityContextInterface).

This conversion is particularly useful to make idcard requests, since metadata documents are retrieved from part instances and not geometric instances.

The GeometricInstanceConverterInterface interfaces are created through the createGeometricInstanceConverter method.

The list of signals the GeometricInstanceConverterInterface may trigger is available in the GeometricInstanceConverterInterfaceSignal enumeration.

The conversion mechanism is triggered through the convert method. The result is not available right away, but the event GeometricInstanceConverterReady is triggered when the result of the GeometricInstanceConverterInterfaceSignal is available. The result is available through the getPartInstanceIds function.

Warning : there may be cases when the getPartInstanceIds is not available such as when the GeometricInstanceConverterInterface is fetching data, i.e. when isRunning returns true, or when the GeometricInstanceConverterInterface has been cancelled, i.e. when isCancelled returns true.

A GeometricInstanceConverterInterface may be interrupted (cancelled) when the GeometricInstanceConverterInterface is fetching data and cancel is called. In such cases, the GeometricInstanceConverterCancelled signal is fired, and shortly after, GeometricInstanceConverterReady signal is fired, but getPartInstanceIds will return undefined. Just call convert with another (or the same) geometric instance ids to trigger a new retrieval.

If you call multiple times convert before receiving the GeometricInstanceConverterReady, only one GeometricInstanceConverterReady will be sent with the content of the last call to convert.

This interface performs the opposite operation of the PartInstanceConverterInterface interface.

/** 
 * Sample to illustrate the use of a GeometricInstanceConverterInterface from a `geometric instance id`.
 */
import {
    VisibilityContextInterface, GeometricInstanceConverterInterface, GeometricInstanceConverterInterfaceSignal,
    DataSessionInterface,
} from 'generated/documentation/appinfiniteapi';

// the `geometric instances` are retrieved by a picking for example

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// the `geometric instance id` to get information from
let lGeometricInstanceId : number;
// create a `geometric instance id` converter
const lGeometricConverter : GeometricInstanceConverterInterface = lDataSession.createGeometricInstanceConverter();
// the current filtering context has been created previously
let lVisibilityContext : VisibilityContextInterface;

// the `geometric instance` to get
const lGeometricInstanceIds: Uint32Array = new Uint32Array(1);
lGeometricInstanceIds[0] = lGeometricInstanceId;

const onPartInstanceReady = (_pEvent, _pCallbackData) : void =>
{
    // triggered when we have all the `part instances` of the given geometry
    const lPartInstanceIds : Uint32Array| undefined = lGeometricConverter.getPartInstanceIds();
    if (lPartInstanceIds && (lPartInstanceIds.length > 0))
    {
        // only work if result is valid
        console.log('result found');
        console.log(lPartInstanceIds.join(','));
    }
}

// connect the GeometricInstanceConverterReady signal to the id card retrieval
lGeometricConverter.addEventListener(GeometricInstanceConverterInterfaceSignal.GeometricInstanceConverterReady, onPartInstanceReady);

// trigger the conversion
lGeometricConverter.convert(lGeometricInstanceIds, lVisibilityContext);

Or with async calls :

/** 
 * Sample to illustrate the asynchronous use of a GeometricInstanceConverterInterface from a `geometric instance id`.
 */
import {
    VisibilityContextInterface, GeometricInstanceConverterInterface, AsyncUInt32ArrayResult, AsyncResultReason,
    DataSessionInterface,
} from 'generated/documentation/appinfiniteapi';

// the `geometric instances` are retrieved by a picking for example

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// the `geometric instance id` to get information from
let lGeometricInstanceId : number;
// create a `geometric instance id` converter
const lGeometricConverter : GeometricInstanceConverterInterface = lDataSession.createGeometricInstanceConverter();
// the current filtering context has been created previously
let lVisibilityContext : VisibilityContextInterface;

// the `geometric instance` to get
const lGeometricInstanceIds: Uint32Array = new Uint32Array(1);
lGeometricInstanceIds[0] = lGeometricInstanceId;

const convertInstance = async () : Promise<any> =>
{
    // trigger the conversion
    const lResult : AsyncUInt32ArrayResult = await lGeometricConverter.asyncConvert(lGeometricInstanceIds, lVisibilityContext);

    // triggered when we have all the `part instances` of the given geometry
    const lPartInstanceIds : Uint32Array| undefined = lGeometricConverter.getPartInstanceIds();
    console.assert(lResult.value === lPartInstanceIds);
    if (lPartInstanceIds && (lPartInstanceIds.length > 0))
    {
        console.assert(lResult.reason === AsyncResultReason.ARR_Success);
        // only work if result is valid
        console.log('result found');
        console.log(lPartInstanceIds.join(','));
    }
}

convertInstance();

An example with an idcard request :

/** 
 * Sample to illustrate the use of an IdCardGetterInterface from a `geometric instance id`.
 */
import {
    VisibilityContextInterface, IdCardGetterInterface, GeometricInstanceConverterInterface,
    IdCardGetterInterfaceSignal, GeometricInstanceConverterInterfaceSignal, DataSessionInterface,
} from 'generated/documentation/appinfiniteapi';
// the `part instances` are retrieved by a picking for example

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// the `geometric instance id` to get information from
let lGeometricInstanceId : number;
// create a `geometric instance id` converter
const lGeometricConverter : GeometricInstanceConverterInterface = lDataSession.createGeometricInstanceConverter();
// the current filtering context has been created previously
let lVisibilityContext : VisibilityContextInterface;
// what to do when the conversion from picking is ready
let onPartInstanceReady : (pEvent, _pCallbackData) => void;
// what to do when the id card retrieval is over
let onIdCardReady : (pEvent, _pCallbackData) => void;

// id card getter interface creation
const lIdCardGetterInterface : IdCardGetterInterface = lDataSession.createIdCardGetter();
// connect the IDCardReady signal to the handling of the metadata of the `part instance` and its genealogy 
lIdCardGetterInterface.addEventListener(IdCardGetterInterfaceSignal.IdCardReady, onIdCardReady);

// the `geometric instance` to get
const lGeometricInstanceIds: Uint32Array = new Uint32Array(1);
lGeometricInstanceIds[0] = lGeometricInstanceId;
// connect the GeometricInstanceConverterReady signal to the id card retrieval
lGeometricConverter.addEventListener(GeometricInstanceConverterInterfaceSignal.GeometricInstanceConverterReady, onPartInstanceReady);

onPartInstanceReady = (_pEvent, _pCallbackData) : void =>
{
    // triggered when we have all the `part instances` of the given geometry
    const lPartInstanceIds : Uint32Array| undefined = lGeometricConverter.getPartInstanceIds();
    if (lPartInstanceIds && (lPartInstanceIds.length > 0))
    {
        // only get the idcard of the first `part instance` (we may do other things if multiple idcards to retrieve)
        // onIdCardReady will be called shortly after
        lIdCardGetterInterface.retrieveIdCard(lPartInstanceIds[0], lVisibilityContext);
    }
}

// trigger the conversion
lGeometricConverter.convert(lGeometricInstanceIds, lVisibilityContext);

Please refer to [IdCardGetterInterface](IdCardGetterInterface.html) for more information about idcard requests.

See

GeometricInstanceConverterInterfaceSignal