Math Sculptor Interfaces
The code below describe a set of interfaces and helper classes for creating addin tools. Essentially, these interfaces are used to encapsulate algorithms (or anything that returns point locations given a UV parameters) so that they can be used by other applications.
ISculptAddin is the key public interface your new tool must support. A second interface called ISculptParam provides a way of passing parameters to your algorithm or function.
Essentially, there are two main concepts, an algorithm that in this case is a simple function called getXYZ() and parameters which can be set to get variations on the algorithm's output. The remaining methods and properties simply return information about the algorithm, parameters, and the addin tool. This includes names of parameters, descriptions, and an image to represent the "addin" tool.
Note that generics are used for parameters. The existing Math Sculptor application makes use of input parameters of bool, int, float and double. However, there is no reason why other types can not be used. Frameworks should simply ignore parameters they do not support and always return the default value.
Note that a ScuptParam<T> class exists with the necessary parameter interfaces already implemented. You are not required to use this class. It is simply a convenience for developers to avoid having to create the "getters" and "setters" for your class.
The code below is a current snapshot of what exists in the ISculptAddin.dl. This is the only dependency your code will have and it has no dependencies (outside of .NET). In theory, these addin's developed using these interfaces can be taken to other "Frameworks". For exmaple, they could be used in your own tool or in commercial applications.
using System;
using System.Collections.Generic;
using System.Text;
using System.Drawing;
using System.ComponentModel;
namespace Burhop.MathSculptor
{
/// <summary>
/// A simple 3 byte structure for X,Y,Z values</summary>
/// <remarks>
/// X,Y,Z values range from 0 to 255</remarks>
public struct xyz
{
/// <summary>
/// X value ranging from 0-255
/// </summary>
public byte x;
/// <summary>
/// Y value ranging from 0-255
/// </summary>
public byte y;
/// <summary>
/// Y value ranging from 0-255
/// </summary>
public byte z;
};
/// <summary>
/// General interface for Math Sculptor Function Parameters. ISculptParam objects
/// are passed between your addin and external code. You generally do not want to
/// implement this interface directly, Rather one of the sub interfaces should be used.
/// </summary>
public interface ISculptParam
{
/// <summary>
/// The Name of the Parameter such as "Height", "Radius","Number", etc.
/// </summary>
string Name
{
get;
}
/// <summary>
/// A brief description of the parameter which might be displayed in a ToolTop
/// </summary>
string Description
{
get;
}
/// <summary>
/// The Type of the parameter, generally the ISculptParm*T* Type child class "/>
/// </summary>
Type Type
{
get;
}
};
/// <summary>
/// A template Interface used to to work with different types. This allows
/// new parameter types to be added as needed. Common types are bool, int, and float
/// </summary>
/// <typeparam name="T">Generally, bool, int, float.</typeparam>
public interface ISculptParam<T> : ISculptParam
{
/// <summary>
/// The current value of this parameter. It should be set initially to the default
/// value of your parameter. The framework (such as Math Sculpt) will set this
/// value and provide it to you on update.
/// </summary>
T Value
{
get;
set;
}
/// <summary>
/// The lowest valid value for this parameter. For example, a radius parameter may
/// only accept values greater than 0.
/// </summary>
T LowValue
{
get;
set;
}
/// <summary>
/// The highest valud value for this parameter. For example, a radius parameter may
/// need to stay bellow 127 to avoid creating cycles outside the 0 to 255 volume of a
/// sculptured primitive.
/// </summary>
T HighValue
{
get;
set;
}
}
/// <summary>
/// The primary Math Sculpt Interface for accessing your alrgorithm/function
/// and for getting information about the Addin Tool to display to the user.
///
/// </summary>
public interface ISculptAddin
{
/// <summary>
/// Gets an XYZ set of values given the u and v parameter
/// </summary>
/// <param name="u">u parameter 0. to 1. </param>
/// <param name="v">v parameter 0. to 1. </param>
/// <returns>The XYZ coordinate for that parameter pair</returns>
xyz getXYZ(double u, double v);
/// <summary>
/// An small image to display in the UI. It should give a hit as to what your
/// AddinTool does.
/// </summary>
System.Drawing.Image IconImage
{
get;
}
/// <summary>
/// Short Description of the Addin Tool, usually less than 80 characters. For
/// Math Sculpt, this will be displayed in the UI.
/// </summary>
string Description
{
get;
}
/// <summary>
/// A long Description of the Addin Tool that provides additional information.
/// </summary>
string LongDescription
{
get;
}
/// <summary>
/// Provides a list of the parameters for this Addin Tool. On start up,
/// the frameworkk will ask for the list of parameters and create the
/// the corresponding UI needed to modify them. As the values change, the
/// parameters are "set". The Framework is expected to pass back
/// the list of parameters to your addin in the same order it was given.
/// </summary>
List<ISculptParam> Params
{
get;
set;
}
}
/// <summary>
/// Provides a contrete utility class for common Parameters
/// This class should not be used in any Frameworks. It is a utility class
/// for Addin developers.
/// </summary>
public abstract class SculptParam : ISculptParam
{
string name;
string description;
/// <summary>
/// The Name of the Parameter such as "Height", "Radius","Number", etc.
/// </summary>
public string Name
{
get { return name; }
set { name = value; }
}
/// <summary>
/// A brief description of the parameter which might be displayed in a ToolTop
/// </summary>
public string Description
{
get { return Description; }
set { description = value; }
}
/// <summary>
/// The Type of the parameter, generally the ISculptParm*T* Type child class "/>
/// </summary>
public abstract Type Type { get;}
}
/// <summary>
/// Provides a contrete utility template class for Parameters
/// This class should not be used in any Frameworks. It is a utility class
/// for Addin developers to avoid having to implement the same code over and over.
/// For example, for interger parameters, use "int" as the Type.
/// </summary>
public class SculptParam<T> : SculptParam,ISculptParam<T>
{
T value;
T highValue;
T lowValue;
public override Type Type
{
get { return typeof(ISculptParam<T>); }
}
public T Value
{
get { return value; }
set {this.value = value;}
}
public T LowValue
{
get { return lowValue; }
set { this.lowValue = value; }
}
public T HighValue
{
get{ return highValue; }
set { this.highValue = value; }
}
}
}