Collection

Introduction

vtkCollection is a container of multiple vtkObject items.
This can be useful for encapsulating multiple vtkObjects such as images
into a single vtkObject (vtkCollection instance) to be passed as input
to other filters and mappers as a single unit.

Methods

addItem

Add item (vtkObject) to the collection

Argument	Type	Required	Description
item	vtkObject	Yes	item to be added to the collection

empty

Check if the collection is empty

extend

Method used to decorate a given object (publicAPI+model) with vtkCollection characteristics.

Argument	Type	Required	Description
publicAPI		Yes	object on which methods will be bounds (public)
model		Yes	object on which data structure will be bounds (protected)
initialValues	ICollectionInitialValues	No	(default: {})

getItem

get the current item and provided index, returns null if index is out of bounds

getNumberOfItems

Get the total number of items in the collection

insertItem

Add item (vtkObject) to the collection at the given index.
This differs from VTK-C++ where insertItem inserts at position
after the provided index value.

Argument	Type	Required	Description
idx	number	Yes	index where the new item should be inserted.
item	vtkObject	Yes	item to be inserted

isItemPresent

Check if a provided item is already present in the collection

newInstance

Method used to create a new instance of vtkCollection.

Argument	Type	Required	Description
initialValues	ICollectionInitialValues	No	for pre-setting some of its content

removeAllItems

Remove all items from the collection

removeItem

Remove an existing item from the collection

Argument	Type	Required	Description
inValue	number or vtkObject	Yes	index or reference of an item to be removed

replaceItem

Replace an existing item (vtkObject) with a new one

Argument	Type	Required	Description
idx	number	Yes	index of item to be replaced
item	vtkObject	Yes

updateMTimeWithElements

Check each element for modified time and update the collection’s
MTime to the latest timestamp from individual items in the collection.

Source

index.d.ts

import { vtkObject } from '../../../interfaces';
import { Nullable } from '../../../types';

/**
 *
 */
export interface ICollectionInitialValues {
  collection?: vtkObject[];
}

export interface vtkCollection extends vtkObject {
  /**
   * Add item (vtkObject) to the collection
   * @param {vtkObject} item item to be added to the collection
   */
  addItem(item: vtkObject): void;

  /**
   * Add item (vtkObject) to the collection _at_ the given index.
   * This differs from VTK-C++ where insertItem inserts at position
   * after the provided index value.
   * @param {number} idx index where the new item should be inserted.
   * @param {vtkObject} item item to be inserted
   */
  insertItem(idx: number, item: vtkObject): void;

  /**
   * Replace an existing item (vtkObject) with a new one
   * @param {number} idx index of item to be replaced
   * @param {vtkObject} item
   */
  replaceItem(idx: number, item: vtkObject): void;

  /**
   * Remove an existing item from the collection
   * @param {number|vtkObject} inValue index or reference of an item to be removed
   */
  removeItem(inValue: number | vtkObject): void;

  /**
   * Remove all items from the collection
   */
  removeAllItems(): void;

  /**
   * Check if a provided item is already present in the collection
   */
  isItemPresent(item: vtkObject): boolean;

  /**
   * Get the total number of items in the collection
   */
  getNumberOfItems(): number;

  /**
   * Check if the collection is empty
   */
  empty(): boolean;

  /**
   * get the current item and provided index, returns null if index is out of bounds
   */
  getItem(idx: number): Nullable<vtkObject>;

  /**
   * Execute a passed function on every item in the collection
   * @param callbackfn callback function to be executed on every item in the collection
   */
  forEach<T>(
    callbackfn: (value: T, index: number, array: readonly T[]) => void
  ): void;

  /**
   * Execute a passed function on every item in the collection, in order to calculate an aggregated return value.
   * @param callbackfn callback function to be used for aggregating a single value from each item in the collection
   * @param initialValue starting value to calculate aggregation
   */
  reduce<T>(
    callbackfn: (
      previousValue: T,
      currentValue: T,
      currentIndex: number,
      array: readonly T[]
    ) => T,
    initialValue: T
  ): T;

  /**
   * Similar to forEach, but returns an array of resulting values.
   * @param callbackfn callback function to execute on each item in the collection, that returns a value.
   */
  map<T>(
    callbackfn: (value: T, index: number, array: readonly T[]) => void
  ): void;

  /**
   * Check each element for modified time and update the collection's
   * MTime to the latest timestamp from individual items in the collection.
   */
  updateMTimeWithElements(): void;
}

/**
 * Method used to decorate a given object (publicAPI+model) with vtkCollection characteristics.
 *
 * @param publicAPI object on which methods will be bounds (public)
 * @param model object on which data structure will be bounds (protected)
 * @param {ICollectionInitialValues} [initialValues] (default: {})
 */
export function extend(
  publicAPI: object,
  model: object,
  initialValues?: ICollectionInitialValues
): void;

/**
 * Method used to create a new instance of vtkCollection.
 * @param {ICollectionInitialValues} [initialValues] for pre-setting some of its content
 */
export function newInstance(
  initialValues?: ICollectionInitialValues
): vtkCollection;

/**
 * vtkCollection is a container of multiple vtkObject items.
 * This can be useful for encapsulating multiple vtkObjects such as images
 * into a single vtkObject (vtkCollection instance) to be passed as input
 * to other filters and mappers as a single unit.
 */
export declare const vtkCollection: {
  newInstance: typeof newInstance;
  extend: typeof extend;
};
export default vtkCollection;

index.js

import macro from 'vtk.js/Sources/macros';

const { vtkErrorMacro } = macro;

// ----------------------------------------------------------------------------
// vtkCollection methods
// ----------------------------------------------------------------------------

function vtkCollection(publicAPI, model) {
  // Set our className
  model.classHierarchy.push('vtkCollection');

  publicAPI.addItem = (item) => {
    model.collection.push(item);
    publicAPI.modified();
  };

  publicAPI.insertItem = (idx, item) => {
    if (idx < 0 || model.collection.length < idx) {
      vtkErrorMacro('idx out of bounds for insertion.');
    }
    model.collection.splice(idx, 0, item);
    publicAPI.modified();
  };

  publicAPI.replaceItem = (idx, item) => {
    model.collection.splice(idx, 1, item);
    publicAPI.modified();
  };

  publicAPI.removeItem = (inValue) => {
    const idx =
      typeof inValue === 'number' ? inValue : model.collection.indexOf(inValue);
    if (idx >= 0 && idx < model.collection.length) {
      model.collection.splice(idx, 1);
      publicAPI.modified();
    } else {
      vtkErrorMacro('idx out of bounds for removeItem.');
    }
  };

  publicAPI.removeAllItems = () => {
    model.collection = [];
    publicAPI.modified();
  };

  publicAPI.isItemPresent = (item) => model.collection.includes(item);

  publicAPI.getNumberOfItems = () => model.collection.length;

  publicAPI.empty = () => model.collection.length === 0;

  publicAPI.getItem = (idx) => model.collection[idx];

  publicAPI.forEach = (ftor) => {
    model.collection.forEach(ftor);
    // Call modified() for the collection, since ftor could have modified the elements.
    publicAPI.updateMTimeWithElements();
  };

  publicAPI.reduce = (ftor, initialValue) =>
    model.collection.reduce(ftor, initialValue);

  publicAPI.map = (ftor) => model.collection.map(ftor);

  publicAPI.updateMTimeWithElements = () => {
    let maxMTimeOfItems = 0; // we expect time values to be positive numbers
    for (let i = 0; i < model.collection.length; ++i) {
      const elem = model.collection[i];
      maxMTimeOfItems = Math.max(maxMTimeOfItems, elem.getMTime());
    }

    if (maxMTimeOfItems > publicAPI.getMTime()) {
      publicAPI.modified();
    }
  };
}

// ----------------------------------------------------------------------------
// Object factory
// ----------------------------------------------------------------------------

const DEFAULT_VALUES = {
  collection: [],
};

// ----------------------------------------------------------------------------

export function extend(publicAPI, model, initialValues = {}) {
  Object.assign(model, DEFAULT_VALUES, initialValues);

  // Object methods
  macro.obj(publicAPI, model);

  // Object specific methods
  vtkCollection(publicAPI, model);
}

// ----------------------------------------------------------------------------

export const newInstance = macro.newInstance(extend, 'vtkCollection');

// ----------------------------------------------------------------------------

export default { newInstance, extend };