MathSculptorInterface

I'm still in the process of updating the documentation... Please check back shortly. Burhop Piccard 14:01, 24 June 2007 (PDT)

Introduction

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 paramters) so that they can be used by other applications.

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 MathSculptor application makes use of input parameters of bool, int, and double. However, there is no reason why other types can not be used.

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; }
        }
    }
}