Package heronarts.lx.model

Class LXModel

java.lang.Object
heronarts.lx.model.LXNormalizationBounds
heronarts.lx.model.LXModel
All Implemented Interfaces:
LXSerializable
Direct Known Subclasses:
GridModel, GridModel.Strip, LXFixture.Submodel, LXView, StripModel
public class LXModel extends LXNormalizationBounds implements LXSerializable
An LXModel is a representation of a set of points in 3D space. Each LXPoint corresponds to a single point. Though the positions of points may be updated, a model is immutable. Its overall structure, number of points, and hierarchy of submodels may not be changed once it has been created. This class should generally not be used directly to construct model objects. It is heavily preferred to use the LXStructure and LXFixture APIs to dynamically generate a model. In cases where fixed-model programming is preferred, it is recommended to use the LXModelBuilder class to aid in model construction.

  • Field Details

    • transform

      public final LXMatrix transform
      A transform matrix that represents the positioning of this model in the global space, if part of the structure. For manually constructed models this value is undefined.

    • points

      public final LXPoint[] points
      An immutable list of all the points in this model

    • metaData

      public final Map<String,String> metaData
      An immutable map of String key/value pairs, metadata on the model object

    • children

      public final LXModel[] children
      An immutable list of all the children of this model

    • outputs

      public final List<LXOutput> outputs
      An ordered list of outputs that should be sent for this model.

    • tags

      public final List<String> tags
      A list of String tags by which this model type can be identified. Tags are non-empty strings. These tags can be used with the children(String) and sub(String) methods to dynamically navigate this model's hierarchy.

    • size

      public final int size
      Total number of points in the model

    • center

      @Deprecated public final LXVector center
      Deprecated.
      Center position in the model (half-way between extremes)

    • average

      @Deprecated public final LXVector average
      Deprecated.
      Average position in the model (weighted by point density)

    • ax

      public float ax
      Average x point

    • ay

      public float ay
      Average y point

    • az

      public float az
      Average z point

    • rMin

      public float rMin
      Smallest radius from origin (0, 0)

    • rMax

      public float rMax
      Greatest radius from origin (0, 0)

    • rRange

      public float rRange
      Range of radial values from origin (0, 0)

    • rcMin

      public float rcMin
      Smallest radius from center of model, this is only valid on the top-level LXModel

    • rcMax

      public float rcMax
      Greatest radius from center of model, this is only valid on the top-level LXModel

    • rcRange

      public float rcRange
      Range of radial values from center of model, only valid on the top-level LXModel

    • azimuth

      public float azimuth
      Angle of this model's center about the origin in the x-z plane (clockwise rotation about the upwards vertical Y-axis) 0 is pointing straight ahead (+z axis) HALF_PI is to the right (+x axis) PI is backwards (-z axis) 1.5*PI is to the left (-x axis)

    • elevation

      public float elevation
      Angle of this point between the y-value and the x-z plane 0 is flat HALF_PI is upwards (+y axis) -HALF_PI is downwards (-y axis)

  • Constructor Details

    • LXModel

      public LXModel()
      Constructs a null model with no points

    • LXModel

      public LXModel(List<LXPoint> points)
      Constructs a model from a list of points
      Parameters:
      points - Points in the model

    • LXModel

      public LXModel(List<LXPoint> points, String... tags)
      Constructs a model from a list of points
      Parameters:
      points - Points in the model
      tags - Tag identifiers for the model type

    • LXModel

      public LXModel(List<LXPoint> points, Map<String,String> metaData, String... tags)
      Constructs a model from a list of points
      Parameters:
      points - Points in the model
      metaData - Metadata for the model
      tags - Tag identifiers for the model type

    • LXModel

      public LXModel(List<LXPoint> points, LXModel[] children)
      Constructs a model with a given set of points and pre-constructed children. In this case, points from the children are not added to the points array, they are assumed to already be contained by the points list.
      Parameters:
      points - Points in this model
      children - Pre-built direct child model array

    • LXModel

      public LXModel(List<LXPoint> points, LXModel[] children, String... tags)
      Constructs a model with a given set of points and pre-constructed submodels. In this case, points from the submodels are not added to the points array, they are assumed to already be contained by the points list.
      Parameters:
      points - Points in this model
      children - Pre-built direct submodel child array
      tags - Tag identifier for this model

    • LXModel

      public LXModel(List<LXPoint> points, LXModel[] children, LXNormalizationBounds bounds, String... tags)
      Constructs a model with a given set of points and pre-constructed submodels. In this case, points from the submodels are not added to the points array, they are assumed to already be contained by the points list.
      Parameters:
      points - Points in this model
      children - Pre-built direct submodel child array
      bounds - Normalization bounds
      tags - Tag identifier for this model

    • LXModel

      public LXModel(List<LXPoint> points, LXModel[] children, Map<String,String> metaData, String... tags)
      Constructs a model with a given set of points and pre-constructed submodels. In this case, points from the submodels are not added to the points array, they are assumed to already be contained by the points list.
      Parameters:
      points - Points in this model
      children - Pre-built direct submodel child array
      metaData - Metadata map
      tags - Tag identifier for this model

    • LXModel

      public LXModel(List<LXPoint> points, LXModel[] children, Map<String,String> metaData, List<String> tags)
      Constructs a model with a given set of points and pre-constructed submodels. In this case, points from the submodels are not added to the points array, they are assumed to already be contained by the points list.
      Parameters:
      points - Points in this model
      children - Pre-built direct submodel child array
      metaData - Metadata map
      tags - Tag identifier for this model

    • LXModel

      public LXModel(List<LXPoint> points, LXModel[] children, LXNormalizationBounds bounds, Map<String,String> metaData, List<String> tags)
      Constructs a model with a given set of points and pre-constructed submodels. In this case, points from the submodels are not added to the points array, they are assumed to already be contained by the points list.
      Parameters:
      points - Points in this model
      children - Pre-built direct submodel child array
      bounds - Normalization bounds, if different from the model itself
      metaData - Metadata map
      tags - Tag identifier for this model

    • LXModel

      public LXModel(LXModel[] children)
      Constructs a model from the given submodels. The point list is generated from all points in the submodels, on the assumption that they have not yet been added.
      Parameters:
      children - Sub-models

    • LXModel

      public LXModel(LXModel[] children, LXNormalizationBounds bounds)
      Constructs a model from the given submodels. The point list is generated from all points in the submodels, on the assumption that they have not yet been added.
      Parameters:
      children - Sub-models
      bounds - Bounds

    • LXModel

      public LXModel(LXModel[] children, LXNormalizationBounds bounds, String... tags)
      Constructs a model from the given submodels. The point list is generated from all points in the submodels, on the assumption that they have not yet been added.
      Parameters:
      children - Sub-models
      bounds - Normalization bounds
      tags - Tags

    • LXModel

      @Deprecated public LXModel(LXModelBuilder builder)
      Deprecated.

    • LXModel

      @Deprecated protected LXModel(LXModelBuilder builder, boolean isRoot)
      Deprecated.

  • Method Details

    • validateTags

      public static List<String> validateTags(List<String> tags)

    • getNormalizationBounds

      public LXNormalizationBounds getNormalizationBounds()
      Returns the model which defines the space in which this model's points are normalized, based upon the xMin/xMax/xRange etc. By default, this is the model itself.
      Returns:
      Model that defines normalization ranges for points

    • getRoot

      public LXModel getRoot()
      Returns the root model that this is derived from
      Returns:
      Root model that this model belongs to, potentially this

    • getParent

      public LXModel getParent()
      Returns the larger model which contains this model, if there is one. May be null.
      Returns:
      Model containing this model, or null

    • contains

      public boolean contains(LXModel descendant)
      Determine whether the given descendant is contained by this model, at any level of hierarchy.
      Parameters:
      descendant - Descendant submodel
      Returns:
      true if the descendant is contained by this model tree

    • getPath

      public String getPath()

    • reindexPoints

      public LXModel reindexPoints()
      Reindexes all the points in this model from 0 up to the number of points.
      Returns:
      this

    • children

      public List<LXModel> children(String tag)
      Returns a list of all the direct child components by particular tag. Children are only one-level deep.
      Parameters:
      tag - Child tag type
      Returns:
      List of direct children by type

    • sub

      public List<LXModel> sub(String tag)
      Returns a list of all the submodel components by particular tag, at any level of depth, may be many levels of descendants contained here
      Parameters:
      tag - Submodel tag
      Returns:
      List of all descendant submodels

    • ancestor

      public LXModel ancestor(String tag)
      Returns the first ancestor of this model with the given tag, if it exists.
      Parameters:
      tag - Tag to search ancestors for
      Returns:
      Nearest ancestor with tag, or null

    • meta

      public String meta(String key)
      Gets a meta data property
      Parameters:
      key - Meta data key
      Returns:
      Value if there is one, otherwise null

    • addListener

      public final LXModel addListener(LXModel.Listener listener)

    • removeListener

      public final LXModel removeListener(LXModel.Listener listener)

    • update

      public LXModel update()
      Update the meta-values in this model. Re-normalizes the points relative to this model and recomputes its averages.
      Returns:
      this

    • update

      public LXModel update(boolean normalize)
      Update the averages and mins/maxes of the model.
      Parameters:
      normalize - If true, normalize the points relative to this model
      Returns:
      this

    • update

      public LXModel update(boolean normalize, boolean recurse)
      Updates the averages and min/maxes of the model
      Parameters:
      normalize - If true, normalize the points relative to this model
      recurse - If true, compute averages for sub-models as well
      Returns:
      this

    • bang

      public LXModel bang()
      Should be invoked when some of the geometry inside a model has been changed, but the total point count and structure is the same. Will increment a sentinel value and notify listeners of the change.
      Returns:
      this

    • getGeneration

      public int getGeneration()
      Returns an integer identifying the generation of this model. Each time geometry in the model is changed, this value is incremented;
      Returns:
      Monotonically increasing integer verson number of the geometry revision

    • toIndexBuffer

      public int[] toIndexBuffer()
      Creates an index buffer of all the point indices in this model.
      Returns:
      Index buffer of all points in this model, containing their global color indices

    • toIndexBuffer

      public int[] toIndexBuffer(int offset, int length)
      Creates an index buffer of a subset of points in this model.
      Parameters:
      offset - Initial offset into this model's points
      length - Length of the index buffer
      Returns:
      Array that contains the global color buffer indices for the specified points in this model

    • normalizePoints

      public LXModel normalizePoints()
      Sets the normalized values of all the points in this model (xn, yn, zn) relative to this model's absolute bounds.
      Returns:
      this

    • getPoints

      public List<LXPoint> getPoints()
      Accessor for a list of all points in the model. Generally preferable to directly access the points array when iterating over a full buffer, but this is useful for situations where a container is needed.
      Returns:
      List of all points

    • getGeometry

      public float[] getGeometry(LXModel.Geometry geometry)
      Gets a computed geometry array for all the points in this model, indexed by LXPoint.index. Note that the array is not guaranteed to be complete, it will only contain valid values for points in this model. This method makes use of caching and should be cheap for repeated calls on the same model, but could incur significant CPU cost the first time it is invoked for a given geometry type, or if the model geometry has changed.
      Parameters:
      geometry - Geometry type
      Returns:
      Geometry array

    • getGeometry

      public float[] getGeometry(LXModel.GeometryFunction function)
      Gets a computed geometry array for all the points in this model, indexed by LXPoint.index. Note that the array is not guaranteed to be complete, it will only contain valid values for points in this model. This method makes use of caching and should be cheap for repeated calls on the same model, but could incur significant CPU cost the first time it is invoked for a given geometry type, or if the model geometry has changed.
      Parameters:
      function - Geometry function
      Returns:
      Geometry array

    • computeGeometry

      public float[] computeGeometry(LXModel.GeometryFunction function)
      Dynamically computes an array of geometry values for all the points in this model. This is an expensive CPU operation that runs math against all points in the model, it should be used carefully and results should be cached if desired.
      Parameters:
      function - Geometry function
      Returns:
      Array of geometry values indexed by LXPoint.index

    • save

      public void save(LX lx, JsonObject object)
      Description copied from interface: LXSerializable
      Serializes this instance into the JSON object
      Specified by:
      save in interface LXSerializable
      Parameters:
      lx - LX instance
      object - Object to serialize into

    • load

      public void load(LX lx, JsonObject object)
      Description copied from interface: LXSerializable
      Restores this instance from a JSON object
      Specified by:
      load in interface LXSerializable
      Parameters:
      lx - LX instance
      object - Object to deserialize

    • dispose

      public void dispose()

    • debugPrint

      public void debugPrint(PrintStream out)