SIM/SIM_RawIndexField.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Jeff Lait
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        SIM_RawendexField.h ( SIM Library, C++)
 *
 * COMMENTS:
 *              An RawIndexField tracks a per-voxel index so one can
 *              convert a raw field to a linear coordinate system
 *              and back again.
 */

#ifndef __SIM_RawIndexField__
#define __SIM_RawIndexField__

#include "SIM_API.h"

#include <UT/UT_VoxelArray.h>

#include "SIM_RawField.h"

/// Voxel boxes are used to define voxel groups
struct SIM_API SIM_VoxelBox
{
    SIM_VoxelBox();
    SIM_VoxelBox(
        const int xMin, const int yMin, const int zMin,
        const int xEnd, const int yEnd, const int zEnd
    );

    bool contains(const int x, const int y, const int z) const;

    // Represent all voxels v with begin[d] <= v[d] < end[d] for d < 3.
    int begin[3];
    int end[3];
};

class SIM_API SIM_RawIndexField
{
public:
    typedef UT_RefArray<int64> Indices;
    typedef SIM_VoxelBox Box;
    typedef UT_RefArray<Box> Boxes;

             SIM_RawIndexField();
    virtual ~SIM_RawIndexField();

    /// Copy constructor:
                SIM_RawIndexField(const SIM_RawIndexField &src);

    /// Assigment operator:
    const SIM_RawIndexField     &operator=(const SIM_RawIndexField &src);               

    /// Initializes the field.
    /// The resolution given is in terms of voxels, the actual dimensions
    /// of this field may be slightly different due to the sampling
    /// choice.
    void        init(SIM_FieldSample sample, 
                     const UT_Vector3 &orig, const UT_Vector3 &size,
                     int xres, int yres, int zres);

    /// Initialize this to be the same dimension and sampling
    /// patern as the given field.
    void        match(const SIM_RawField &src);
    void        match(const SIM_RawIndexField &src);
    
    /// Convert indices to world coordinates and vice-versa.  Note this uses
    /// this field's indices which change depending on sampling.
    bool                 indexToPos(int x, int y, int z, UT_Vector3 &pos) const;

    /// Converts a worldspace position into an integer index.
    bool                 posToIndex(UT_Vector3 pos, int &x, int &y, int &z) const;

    /// Returns true if the given field and this one match in terms
    /// of number of voxels and bounding box size.
    /// This means the voxel cells match - not necessarily the sample
    /// points!
    bool        isMatching(const SIM_RawIndexField *field) const;

    /// Returns true if the two fields are precisely aligned.  This
    /// means that samples are matched so a given integer index
    /// into either field would give the same result.
    bool        isAligned(const SIM_RawIndexField *field) const;
    bool        isAligned(const SIM_RawField *field) const;

    int64                getMemoryUsage() const;
    
    /// Returns the resolution of the voxel grid that we are sampling.
    /// This is a count of voxels, so may differ for our different
    /// sampling methods.
    void                 getVoxelRes(int &xres, int &yres, int &zres) const;

    const UT_Vector3    &getVoxelSize() const { return myVoxelSize; }
    fpreal               getVoxelDiameter() const { return myVoxelDiameter; }

    /// Returns true if the given x, y, z values lie inside the valid index.
    bool         isValidIndex(int x, int y, int z) const
                 {
                     return field()->isValidIndex(x, y, z);
                 }
    
    /// Builds from a surface & collision field.
    /// -1 if inside collision, -2 if not in collision and not in
    /// surface, otherwise a unique number.
    /// Returns maximum index (which you can also get from getMaxIndex)
    int64       buildIndex(const SIM_RawField *surface,
                           const SIM_RawField *collision);
    
    // Expanded version of build index.
    // Partitions the voxels into sets.
    // Sets in the partition are defined as follows:
    // All voxels in box #i will end up in set i.
    // Voxels that don't fall into any box fall into the last set.
    // In the resulting index the voxels in group 0 will have indices
    // 0 ... setEnds[0]. Voxels in group i will have indices 
    // setEnds[i] ... setEnds[i + 1].
    // When allowSubdivide is false, the partition will have only one set.
    // Otherwise, the partition will have multiple sets.
    int64       buildPartitionedIndex(const SIM_RawField *surface,
                                      const SIM_RawField *collision,
                                      const bool allowSubdivide,
                                      Indices& setEnds);

    // Each voxel is an index of where we should copy our values
    // to perform a SAME boundary collision.  this should already
    // be inited to the desired resolution.
    // -1 for voxels that don't need collision lookups, otherwise
    // it is x+(y+z*yres)*xres
    // Will only write to non- -1 voxels, so call constant(-1) first.
    THREADED_METHOD1(SIM_RawIndexField, shouldMultiThread(), 
                    buildCollisionLookup,
                    const SIM_RawField *, collision)
    void        buildCollisionLookupPartial(const SIM_RawField *collision,
                                            const UT_JobInfo &info);
    
    /// Computes the connected components of the given field.
    /// Anything with a value < 0 will be considered "inside" and
    /// connected to each other.  Voxels with a value >= 0 will be
    /// flagged as being in component -1.
    /// The maxIndex will store the number of connected components.
    int64       computeConnectedComponents(const SIM_RawField &surface);

    /// Computes the connected components according to the given index
    /// values.  Areas of -1, -2, and >=0 will be consdiered three different
    /// material types and connectivity computed respectively.
    int64       computeConnectedComponents(const SIM_RawIndexField &idx);

    /// Returns true if this should be multithreaded.
    bool        shouldMultiThread() const
                {
                    return field()->numTiles() > 1;
                }

    int64       operator()(int x, int y, int z) const
                {
                    return (*field())(x, y, z);
                }
    int64       getIndex(const UT_VoxelArrayIteratorF &vit) const
                {
                    return (*field())(vit.x(), vit.y(), vit.z());
                }

    int64       getValue(const UT_Vector3 &pos) const;

    UT_VoxelArray<int64> *field() const { return myField; }

    int64       maxIndex() const { return myMaxIndex; }

    const UT_Vector3 &getOrig() const { return myOrig; }
    const UT_Vector3 &getSize() const { return mySize; }
    const UT_Vector3 &getBBoxOrig() const { return myBBoxOrig; }
    const UT_Vector3 &getBBoxSize() const { return myBBoxSize; }

    SIM_FieldSample              getSample() const { return mySample; }

protected:
    /// Given a set of connectivity classes, collapse into the minimal
    /// set and renumber from 0.  myMaxIndex will be updated with the
    /// resulting maximum & the number of components returned.
    int64       collapseClassIndices();

    /// Determines if two indices should be connected using our empty
    /// cell merge rule.
    bool        shouldConnectIndices(int64 idx1, int64 idx2) const;
    
    UT_VoxelArray<int64>        *myField;
    SIM_FieldSample              mySample;
    int64                        myMaxIndex;

    // This is the size and offset which converts our UT_VoxelArray into
    // world coordinates.
    UT_Vector3                   myOrig, mySize;

    // This is our actual official size.
    UT_Vector3                   myBBoxOrig, myBBoxSize;

    // Cached metrics.
    UT_Vector3                   myVoxelSize;
    fpreal                       myVoxelDiameter;

    // Find ranges of indices for valid voxels
    void findRange
    (
        const SIM_RawField* surface,
        const SIM_RawField* collision,
        int begin[3],
        int end[3]
    ) const;

    // Count all valid voxels in a box
    int64 countVoxelsInBox
    (
        const SIM_RawField* surface,
        const SIM_RawField* collision,
        const Box& box
    ) const;
};

// Indexed field enriched with a grouping structure
struct SIM_API SIM_PartitionedRawIndexField
{
    SIM_RawIndexField myIndex;
    /// Group i has index range groupEnd(i-1) ... groupEnd(i)-1,
    /// where groupEnd(-1) = 0
    SIM_RawIndexField::Indices mySetEnds;

    // Similar to SIM_RawIndexField::buildIndex.
    // A grouped index is built based on boxes.
    int64 buildIndex(const SIM_RawField *surface,
                     const SIM_RawField *collision);
};

#endif

---