MegaShape API

This page guides you through the various classes that make up the Spline system inside MegaShapes. A MegaShape is made up of MegaSplines and each spline is in turn made from MegaKnots. Each MegaShape can have any number of MegaSplines to define its overall shape, each of those MegaSplines can be an open or closed shape and can contain any number of MegaKnots. A MegaKnot is the class which actually holds the position of the knot in local space as well as the position of the handles that control the in and out tangents to the knot.

If you wish to add more knots to a spline you only need to create a new MegaKnot class using new and then Add the knot to the list or insert it into the list. You can also use the methods shown below to add knots to a spline.

MegaKnot

Class

public class MegaKnot
{
    public Vector3  p;
    public Vector3  invec;
    public Vector3  outvec;
    public float    seglength;
    public float    length;
    public bool     notlocked;
}

Param Members

p

The position in local space of the actual knot

invec

The position in local space of the in vector handle

outvec

The position in local space of the out vector handle

seglength

The length of this curve segment to the next knot

length

The length from the start of the curve to this knot

notlocked

Used by the editor to say handles should be locked

Methods

public MegaKnot()

Creates a new empty knot.

public Vector3 Interpolate(float t, MegaKnot k)
t – Interpolation value, value in the 0 to 1 range
k – the knot to interpolate to, usually this is the next knot

This will return the local position of a point on the curve segment between the knot and the one passed in, so if t = 0.0f it will return the current knot position, 1 will return the position of the passed in knot k.

MegaSpline

Class

public class MegaSpline
{
    public float              length;
    public bool               closed;
    public List<MegaKnot>     knots;
    public List<MegaKnotAnim> animations;
    public Vector3            offset;
    public Vector3            rotate;
    public Vector3            scale;
}

Param Members

length

The length of the spline

closed

Is the spline closed or open

knots

The List of knots that make up this spline

animations

Animation data for the knots

offset

Offset in local space for the spline

rotate

Local euler rotation of the spline

scale

Local scale

Methods

static public MegaSpline Copy(MegaSpline src)
src – Spline to copy

This will return a new copy of the spline passed to it.

public void AddKnot(Vector3 p, Vector3 invec, Vector3 outvec)
p – Local space position of the knot
invec – local space position of the in vector handle
outvec – local space position of the out vector handle

Will create a new knot from the values passed in and add it to the end of the knot list for this spline. Note a call should be made to MegaShape CalcLength after you have added or changed any knots.

public void AddKnot(Vector3 p, Vector3 invec, Vector3 outvec, Matrix4x4 tm)
p – Local space position of the knot
invec – local space position of the in vector handle
outvec – local space position of the out vector handle
tm – The matrix to transform the values by before creating the knot

Will create a new knot from the values passed in transformed by the matrix and add it to the end of the knot list for this spline. Note a call should be made to MegaShape CalcLength after you have added or changed any knots.

public bool Contains(Vector3 p)
p – Local space point to check

Will return true if the passed in local space point is inside the spline. If the spline is not closed the method will always return false.

public float Area()

Will return the area covered by the spline, if the spline is not closed it will return 0

public float CalcLength(int steps)
steps – The number of iterations to use in the calculation of the length

Calculates the length of the spline. The step value says how many interations to use in the calculation, a value of 1 would do a simple linear distance between each knot, a value of 10 will produce a very accurate length of the curve.

public Vector3 Interpolate(float alpha, bool type, ref int k)
alpha – the point to return
type – true to use normalized interpolation, false to use linear interpolation
k – On return will hold the knot index the point is in

Returns a local space position on the spline based on the alpha value passed. An alpha value of 0 will return the start of the spline and 1 to end and 0.5 will return the point half way along the length. The type value says whether to use normalized interpolation which is a little slower but gives a smoother result less prone to speed ups that can be seen in some splines. The value returned in ‘k’ is the knot segment the point is in.

public Vector3 InterpCurve3D(float alpha, bool type, ref int k)
alpha – the point to return
type – true to use normalized interpolation, false to use linear interpolation
k – On return will hold the knot index the point is in

This is a more general interpolation method that deals with out of range alpha values correctly, the params are all the same as the above method.

MegaShape

Class

public class MegaShape : MonoBehaviour
{
    public MegaAxis         axis;
    public Color            col1;
    public Color            col2;
    public Color            KnotCol;
    public Color            HandleCol;
    public Color            VecCol;
    public float            KnotSize;
    public float            stepdist; // Distance along whole shape
    public bool             normalizedInterp;
    public bool             drawHandles;
    public bool             drawKnots;
    public bool             drawspline;
    public bool             lockhandles;
    public float            CursorPos;
    public List<MegaSpline> splines;
    public float            time;
    public bool             animate;
    public float            speed;
    public int              selcurve
    public MegaHandleType   handleType;

    // Meshing options
    public bool             makeMesh;
    public MeshShapeType    meshType;
    public bool             DoubleSided;
    public bool             CalcTangents;
    public bool             GenUV;
    public bool             PhysUV;
    public float            Height;
    public int              HeightSegs;
    public int              Sides;
    public float            TubeStep;
    public float            Start;
    public float            End;
    public float            Rotate;
    public Vector3          Pivot;

    // Material 1
    public Vector2          UVOffset;
    public Vector2          UVRotate;
    public Vector2          UVScale;
    public Vector2          UVOffset1;
    public Vector2          UVRotate1;
    public Vector2          UVScale1;
    public Vector2          UVOffset2;
    public Vector2          UVRotate3;
    public Vector2          UVScale3;
    public bool             UseHeightCurve;
    public AnimationCurve   heightCrv;
    public float            heightOff;
}

Param Members

axis

The up axis for when a helper shape is generated, normally this is the Y Axis.

col1

First color to use when the spline gizmos are drawn. Two colours are used so you can see how the interpolation will happen along the spline length, this is useful if you for example use the Path Follow helper script shorter sections will move slower than longer ones.

col2

Second color to use when the spline gizmos are drawn. Two colours are used so you can see how the interpolation will happen along the spline length, this is useful if you for example use the Path Follow helper script shorter sections will move slower than longer ones.

KnotCol

Color to use when displaying the knot gizmos.

HandleCol

Color to use when displaying the handle gizmos.

KnotSize

Size of the knot gizmos.

stepDist

This is the distance the gizmo will step along the spline for each drawn segment, this defines the smoothness of the spline for rendering of the gizmos. This value is also used if the spline is turned into a Mesh so will effect the number of vertices that are generated.

normalizedInterp

You can choose to have the spline interpolated using a simple linear approach or by using a normalized interpolation. The normalised approach will attempt to keep a more constant step along the spline but is slightly slower.

drawHandles

Whether or not the handle gizmos are drawn.

drawKnots

Whether or not the knots are drawn.

drawSpline

Whether or not the spline is displayed.

lockhandles

If lock handels is on dragging one handle will automatically drag the other handle so keeping the knots continuity. Turn this off if you want to control the sharpness of a corner or wish to have different in and out vectors to a knot.

CursorPos

This is the current position along the shape of the editor curor. The cursor is used when new knots are added to the shape in the editor.

splines

The List of splines that make up this shape. A MegaShape can be made up of any number of splines.

time

If the shape is animated then the time is used to control the animation.

animate

Turns the animation on or off.

speed

How fast the animation plays back, a value of 1 is normal speed, 0 will stop the animation and a negative value will play the animation backwards.

selcurve

In editor mode this value controls which spline is currently being edited in the scene.

handleType

Unused currently.

makeMesh

If this is on the mesh will be generated or updated, so if the shape is animated set this to true for the mesh to update as the spline changes.

meshType

Unused currently.

DoubleSided

Will the generated mesh have a back side.

CalcTangents

Calculate the tangents for the generated mesh, this is needed for bump mapping etc.

GenUV

Will UV coordinates be generated for the mesh.

PhysUV

Use physical UV values, this will mean the UV mapping will be based on the vertex positions instead of calculated UV positions.

Height

The height of the extruded mesh generated from the spline.

HeightSegs

Not used currently

Sides

Not used currently

TubeStep

Not used currently

Start

Not used currently

End

Not used currently

Rotate

Not used currently

Pivot

Not used currently

UVOffset

Value to add to the UV coordinates for the front face of the generated mesh.

UVRotate

Rotation amount of the UV coordinates for the front face of the generated mesh.

UVScale

Scale amount for the UV coordinates for the front face of the generated mesh.

UVOffset1

Offset amount for the UV coordinates for the extruded sides of the generated mesh.

UVRotate1

Rotation amount for the UV coordinates for the extruded sides of the generated mesh.

UVScale1

Scale amount for the UV coordinates for the extruded sides of the generated mesh.

UVOffset2

Value to add to the UV coordinates for the front face of the generated mesh.

UVRotate3

Rotation amount of the UV coordinates for the front face of the generated mesh.

UVScale3

Scale amount for the UV coordinates for the front face of the generated mesh.

UseHeightCurve

Controls whether the Height curve is used in the mesh generation.

heightCrv

The curve to control the Up offset of the mesh along its length.

heightOff

The value to multiple the height curve by to get the final height adjustment.

Methods

public MegaSpline NewSpline()

Creates a new empty spline and adds it to the spline list for this shape.

public void Scale(float scale)
scale – the amount to scale the entire shape by

This will scale the intire shape, so all curves and knots.

public float GetCurveLength(int curve)
curve – The curve in the shape to get the length for

Will return the length of the curve whose index is passed, if the index is out of range the length of the first curve will be returned.

public float CalcLength(int curve, int step)
curve – the curve whoes length is to be calculated
step – The number of interpolatin steps to use in the length calculation

This will return the length of the curve whoes index is passed in.

public float CalcLength(int step)
step – The number of interpolation steps to use in the length calculation

Use this to recalculate the length of the all the curves that make up the shape. It is important to call this of the method above if you have altered a shape in anyway, if not then the interpolation methods will not be quite right possibly with a alpha value of 1 not being the end of a curve or falling short.

public Vector3 GetKnotPos(int curve, int knot)
curve – The curve to use
knot – the knot whose position you want

This will return the local space position of the knot whose index is passed in on the curve whose index is passed in.

public Vector3 GetKnotInVec(int curve, int knot)
curve – The curve to use
knot – the knot whose position you want

This will return the local space position of the in vector handle whose index is passed in on the curve whose index is passed in.

public Vector3 GetKnotOutVec(int curve, int knot)
curve – The curve to use
knot – the knot whose position you want

This will return the local space position of the out vector handle whose index is passed in on the curve whose index is passed in.

public void SetKnotPos(int curve, int knot, Vector3 p)
curve – The curve whose knot we are repositioning
knot – The knot we want to position
p – the new local space position of the knot

This will update the knots local space position and update the curves length.

public void SetKnot(int curve, int knot, Vector3 p, Vector3 intan, Vector3 outtan)
curve – The curve whose knot we are repositioning
knot – the knot we want to position
p – the new local space position of the knot
intan – the new local space position of the in vector handle
outtan – the new local space position of the out vector handle

Use this method to completely change a knots position, you pass in the curve and knot index you wish to change and then the new local space positions of the knot and the in and out vector handles. The method will then call CalcLength to update the lengths of the whole shape. If you are going to change a lot of values on a shape at one time then it is best to access the knot data through the arrays directly and update all the values and then call CalcLength() yourself at the end to make it faster.

public void MoveKnot(int curve, int knot, Vector3 p)
curve – The curve whose knot we are repositioning
knot – the knot we want to position
p – the new local space position of the knot

This method will move a knot to a new position and move the tangents along with it. The CalcLength will then be called to update the lengths for the shape. If you are going to change a lot of values on a shape at one time then it is best to access the knot data through the arrays directly and update all the values and then call CalcLength() yourself at the end to make it faster.

public Vector3 InterpCurve3D(int curve, float alpha, bool type)
curve – the curve to interpolate along
alpha – the point to return
type – true to use normalized interpolation, false to use linear interpolation

Returns a local space position on the spline based on the alpha value passed. An alpha value of 0 will return the start of the spline and 1 to end and 0.5 will return the point half way along the length. The type value says whether to use normalized interpolation which is a little slower but gives a smoother result less prone to speed ups that can be seen in some splines. If you pass in values out side of the 0 to 1 range for alpha the function will either interpolate a position before the first knot if the value is < 0 and the spline is open, or interpolate a value past the end of the last knot if the value is > 1 and the spline is open. If the spline is closed then the value will be adjusted to be in the range and then used, so if -1.5 is passed in the value will become 0.5 so the midpoint will be returned.

public Vector3 FindNearestPointWorld(Vector3 p, int iterations, ref int kn, ref Vector3 tangent, ref float alpha)
p – The point in world space to find the nearest point to
iterations – the number of steps taken to find the nearest point, the higher the value the more accurate the result will be
kn – on return this will hold the knot the point is in
tangent – on return this will hold the tangent at the nearest point
alpha – on return this will hold the alpha value along the shape

This method will find the nearest point in the shape to the world space point passed in and return the point in world space. It will also return the knot, the tangent and the alpha value for the point.

public Vector3 FindNearestPoint(Vector3 p, int iterations, ref int kn, ref Vector3 tangent, ref float alpha)
p – The point in the shapes local space to find the nearest point to
iterations – the number of steps taken to find the nearest point, the higher the value the more accurate the result will be
kn – on return this will hold the knot the point is in
tangent – on return this will hold the tangent at the nearest point
alpha – on return this will hold the alpha value along the shape

This method will find the nearest point in the shape to the local space point passed in and return the point in world space. It will also return the knot, the tangent and the alpha value for the point.

public void BuildSpline(int curve, Vector3[] points, bool closed)
curve – The Curve to rebuild
points – The local space points that define the knot positions for the new pline
closed – Whether the new spline is open or closed

This method will rebuild the spline using the Vector3 points array passed in and autocalc the handles for the knots to produce a smooth spline. You can also say whether the spline will be open or closed.

public void BuildSpline(Vector3[] points, bool closed)
points – The local space points array that define the knot position for the new spline
closed – Is the new spline open or closed.

This is like the BuildSpline method above but will create a new spline from the points and add it to the end of the spline list for the shape.

public void AddToSpline(int curve, Vector3[] points)
curve – The curve to add to
points – The array of local space points to extend the spline with.

This will extend the spline chosen by the curve value with the points passed in and calculate the handles.

public void AddToSpline(int curve, Vector3 point)
curve – The spline to add to
point – The local space point to add to the spline

Will extend the spline chosen by the curve value by a single point.

public void AutoCurve(MegaSpline spline)
spline – The spline to calculate the handles for

This will recalc the handles for the spline passed in to make the smoothest shape it can.

public void AutoCurve(MegaSpline spline, int start, int end)
spline – The spline to adjust the handles on
start – The index of the starting knot to smooth
end – The index of the ending knot to smooth

This will calculate the handles for the spline starting with the start index knot and going to the end index knot. This allows you to autosmooth part of a spline.

public void AutoCurve()

This will recalc the handles for all the splines in a shape and recalc the handles to give the smoothest splines.

public void BuildMesh()

Call this to build or rebuild a mesh from the shape.

Code examples

The code below is taken from the MegaShapeCircle.cs and shows how to create a spline in code, this will make a closed circle spline from a radius value, the spline produced is made from 4 knots and the handles for each knot are calculated to form a perfect circle. The important thing to notice is once a spline has been created or altered in any way the CalcLength() method should be called so that the internal lengths of the spline can be calculated for quicker interpolation later, the value passed in will determine how accurate the lengths are, lower values can be used for quicker calculations, 10 gives a very accurate length without too much overhead.

public class MegaShapeCircle : MegaShape
{
    public float Radius = 1.0f;

    const float CIRCLE_VECTOR_LENGTH = 0.5517861843f;

    public override void MakeShape()
    {
        Matrix4x4 tm = GetMatrix();

        float vector = CIRCLE_VECTOR_LENGTH * Radius;
       
        MegaSpline spline = NewSpline();

        for ( int ix = 0; ix < 4; ++ix )
        {
            float angle = (Mathf.PI * 2.0f) * (float)ix / (float)4;
            float sinfac = Mathf.Sin(angle);
            float cosfac = Mathf.Cos(angle);
            Vector3 p = new Vector3(cosfac * Radius, sinfac * Radius, 0.0f);
            Vector3 rotvec = new Vector3(sinfac * vector, -cosfac * vector, 0.0f);
            spline.AddKnot(p, p + rotvec, p - rotvec, tm);
        }

        spline.closed = true;
        CalcLength(10);
    }
}

This is a very simple example that will build a spline from an array of world space points, note you can use local space if you use the BuildSpline method instead, you can also pick which spline in the shape you want to change and also whether or not the spline is open of closed by changing the last param of the BuildSpline method to true.

public class MakeSpline : MonoBehaviour
{
    public MegaShape    shape;      // Shape object
    public Vector3[]    points;     // World space points to make into a spline

    void Start()
    {
        if ( shape && points.Length > 1 )
            shape.BuildSplineWorld(0, points, false);
    }
}

You must be logged in to post a comment.