Softimage SDK Programmer's Guide > Plug-in Development > Modeling >

# Getting the Local Reference Frame

At this time, the SDK does not have an official way to access the local frame reference information. There is, however, a Local Frame Magic Formula for polygon mesh vertices that you can use to evaluate it yourself, or you can use a workaround involving one of the SDK object model's deprecated interfaces.

Tip

Only the magic formula for polygon mesh vertices is provided because it is often used to compute the displacement from local relative shapes on polygon meshes. For other cases, please use the following workaround.

The deprecated Geometry0D, Geometry1D, and Geometry2D interfaces represent the original versions (implemented in v1.0 but deprecated in v1.5) of the Point, Edge, and Facet interfaces, respectively. Each of these interfaces implements a LocalReferenceFrame method which returns the X, Y, and Z axes of the local reference frame at the specified index of the subcomponent.

You can get these deprecated interfaces through the (also deprecated) Geometry_V1 interface, which is available via the CollectionItem.Obj property.

Ok, so here's the catch: the LocalReferenceFrame methods use output objects and so are not available to JScript and the C++ API (Python can handle output arguments from methods without difficulty—see Working with Return Values and Output Arguments for more information). As a workaround, you can implement a custom command (in VBScript) to return an array of these values. That command can then be used by JScript or the C++ API to read the local reference frame, as JScript Example: Using the VBS wrapper to get the Local Reference Frame and C++ Example: Using the VBS wrapper to get the Local Reference Frame illustrate, using a custom command implemented like the one in VBScript Example: Implementing a JScript-compliant version of the LocalReferenceFrame methods or VBScript Example: Implementing a C++ API-compliant version of the LocalReferenceFrame methods.

VBScript Example: Implementing a JScript-compliant version of the LocalReferenceFrame methods

This version of this custom command returns an array containing the output arguments exactly as they are returned from the LocalReferenceFrame methods (that is, a safearray containing the following elements: SIVector3, Boolean, SIVector3, Boolean, SIVector3, Boolean).

Important

The C++ API cannot read the SIVector3 interface and cannot convert it to the CVector3 class, so this version will not work with the C++ API. For a C++ API-compliant version, see VBScript Example: Implementing a C++ API-compliant version of the LocalReferenceFrame methods.

    '
    ' GetLocalReferenceFramePlugin
    '

    ' Registration
    function XSILoadPlugin( in_reg )
    	in_reg.Author = "yourname"
    	in_reg.Name = "GetLocalReferenceFramePlugin"
    	in_reg.Email = "yourname@yourcompany.com"
    	in_reg.URL = "www.yourcompany.com"
    	in_reg.Major = 1
    	in_reg.Minor = 0

    	in_reg.RegisterCommand "GetLocalReferenceFrame","GetLocalReferenceFrame"

    	XSILoadPlugin = true
    end function

    ' De-registration
    function XSIUnloadPlugin( in_reg )
    	strPluginName = in_reg.Name
    	Application.LogMessage strPluginName & " has been unloaded."
    	XSIUnloadPlugin = true
    end function

    ' Set up command arguments, return value and flags
    function GetLocalReferenceFrame_Init( ctxt )
    	dim oCmd
    	set oCmd = ctxt.Source
    	oCmd.Description = "Get Local Reference Frame"
    	oCmd.SetFlag siNoLogging, true
    	oCmd.ReturnValue = true

    	dim oArgs
    	set oArgs = oCmd.Arguments
    	oArgs.AddWithHandler "InputObjs", siArgHandlerCollection
    	oArgs.Add "Index",		siArgumentInput,	,		siInt4
    	oArgs.Add "Dimension",	siArgumentInput,	"0",	siInt2

    	GetLocalReferenceFrame_Init = true
    end function

    ' Main implementation
    function GetLocalReferenceFrame_Execute( InputObjs, Index, Dimension )
    	dim oXDGeometry, aInfoCollection
    	dim oXAxis, oYAxis, oZAxis
    	dim bXAxisValid, bYAxisValid, bZAxisValid

    	set oXAxis = XSIMath.CreateVector3()
    	set oYAxis = XSIMath.CreateVector3()
    	set oZAxis = XSIMath.CreateVector3()

    	' Make sure input object is valid
    	if TypeName(InputObjs(0)) <> "X3DObject" then
    		set GetLocalReferenceFrame_Execute = Nothing
    		Application.LogMessage( "Input object is not a valid object: " & InputObj.Type )
    		exit function
    	end if

    	' Decide which info to get
    	if Dimension = 0 then
    		set oXDGeometry = InputObjs(0).Obj.Geometry0D
    	elseif Dimension = 1 then
    		set oXDGeometry = InputObjs(0).Obj.Geometry1D
    	else
    		set oXDGeometry = InputObjs(0).Obj.Geometry2D
    	end if

    	' Call the correct method and then use the output arguments to populate the array to return
    	oXDGeometry.LocalReferenceFrame i, oXAxis, bXAxisValid, oYAxis, bYAxisValid, oZAxis, bZAxisValid
    	aInfoCollection = Array( oXAxis, bXAxisValid, oYAxis, bYAxisValid, oZAxis, bZAxisValid )

    	' The array returned will be a 1-dimensional SAFEARRAY
    	GetLocalReferenceFrame_Execute = aInfoCollection
    end function

JScript Example: Using the VBS wrapper to get the Local Reference Frame

This example demonstrates how to get the Local Reference Frame information on a cube using JScript. Because JScript cannot handle the output arguments returned by the LocalReferenceFrame methods on the deprecated Geometry0D, Geometry1D, and Geometry2D objects, you must write a custom command in VBScript to extract the information and reformat it for use by JScript. In this example, the expected result is a 1-dimensional safearray containing 3 pairs of SIVector3 and Boolean elements (as implemented in VBScript Example: Implementing a JScript-compliant version of the LocalReferenceFrame methods).

    // Create a cube
    var objItem = CreatePrim( "Cube", "MeshSurface" );

    // Get number of vertices in the cube
    var nbrPoints = objItem.ActivePrimitive.Geometry.Points.Count;

    // Set up some storage for the local reference frame info
    var vc3XAxis = XSIMath.CreateVector3(); var booXAxisValid;
    var vc3YAxis = XSIMath.CreateVector3(); var booYAxisValid;
    var vc3ZAxis = XSIMath.CreateVector3(); var booZAxisValid;

    // Get the local reference frame for each point
    for ( var i=0; i<nbrPoints; i++ ) {
    	var aResults = GetLocalReferenceFrame( objItem, i, 0 ).toArray();
    	vc3XAxis = aResults[0];
    	booXAxisValid = aResults[1];
    	vc3YAxis = aResults[2];
    	booYAxisValid = aResults[3];
    	vc3ZAxis = aResults[4];
    	booZAxisValid = aResults[5];

    	if ( booXAxisValid ) {
    		Application.LogMessage ( "Component [" + i + "] X axis : " + vc3XAxis.x + " | " + vc3XAxis.y + " | " + vc3XAxis.z );
    	} else {
    		Application.LogMessage ( "Component [" + i + "] INVALID X axis" );
    	}

    	if ( booYAxisValid ) {
    		Application.LogMessage ( "Component [" + i + "] Y axis : " + vc3YAxis.x + " | " + vc3YAxis.y + " | " + vc3YAxis.z );
    	} else {
    		Application.LogMessage ( "Component [" + i + "] INVALID Y axis" );
    	}

    	if ( booZAxisValid ) {
    		Application.LogMessage ( "Component [" + i + "] Z axis : " + vc3ZAxis.x + " | " + vc3ZAxis.y + " | " + vc3ZAxis.z );
    	} else {
    		Application.LogMessage ( "Component [" + i + "] INVALID Z axis" );
    	}
    }

    //INFO : Component [0] X axis : 0.408248290463863 | -0.816496580927726 | 0.408248290463863
    //INFO : Component [0] Y axis : -0.577350269189626 | -0.577350269189626 | -0.577350269189626
    //INFO : Component [0] Z axis : 0.707106781186547 | 0 | -0.707106781186547
    //INFO : Component [1] X axis : -0.408248290463863 | 0.408248290463863 | -0.816496580927726
    //INFO : Component [1] Y axis : 0.577350269189626 | -0.577350269189626 | -0.577350269189626
    //INFO : Component [1] Z axis : -0.707106781186547 | -0.707106781186547 | 0
    //INFO : Component [2] X axis : -0.816496580927726 | -0.408248290463863 | 0.408248290463863
    //INFO : Component [2] Y axis : -0.577350269189626 | 0.577350269189626 | -0.577350269189626
    //INFO : Component [2] Z axis : 0 | -0.707106781186547 | -0.707106781186547
    //INFO : Component [3] X axis : -0.408248290463863 | -0.408248290463863 | -0.816496580927726
    //INFO : Component [3] Y axis : 0.577350269189626 | 0.577350269189626 | -0.577350269189626
    //INFO : Component [3] Z axis : 0.707106781186547 | -0.707106781186547 | 0
    //INFO : Component [4] X axis : 0.408248290463863 | -0.816496580927726 | -0.408248290463863
    //INFO : Component [4] Y axis : -0.577350269189626 | -0.577350269189626 | 0.577350269189626
    //INFO : Component [4] Z axis : -0.707106781186547 | 0 | -0.707106781186547
    //INFO : Component [5] X axis : 0.816496580927726 | 0.408248290463863 | -0.408248290463863
    //INFO : Component [5] Y axis : 0.577350269189626 | -0.577350269189626 | 0.577350269189626
    //INFO : Component [5] Z axis : 0 | -0.707106781186547 | -0.707106781186547
    //INFO : Component [6] X axis : -0.816496580927726 | -0.408248290463863 | -0.408248290463863
    //INFO : Component [6] Y axis : -0.577350269189626 | 0.577350269189626 | 0.577350269189626
    //INFO : Component [6] Z axis : 0 | 0.707106781186547 | -0.707106781186547
    //INFO : Component [7] X axis : -0.408248290463863 | 0.816496580927726 | -0.408248290463863
    //INFO : Component [7] Y axis : 0.577350269189626 | 0.577350269189626 | 0.577350269189626
    //INFO : Component [7] Z axis : 0.707106781186547 | 0 | -0.707106781186547

VBScript Example: Implementing a C++ API-compliant version of the LocalReferenceFrame methods

The C++ API cannot read the SIVector3 interface and cannot convert it to the CVector3 class, so this version of the custom command returns an array containing the output arguments flattened (that is, each SIVector3 is expanded in place to its x,y,z values).

Note

Only the implementation is presented here, since all other aspects of the custom command (declaration, initialization) remain the same. See VBScript Example: Implementing a JScript-compliant version of the LocalReferenceFrame methods to see the other callbacks for this command.

    ' Main implementation
    function GetLocalReferenceFrame_Execute( InputObjs, Index, Dimension )
    	dim oXDGeometry, aInfoCollection
    	dim oXAxis, oYAxis, oZAxis
    	dim bXAxisValid, bYAxisValid, bZAxisValid

    	set oXAxis = XSIMath.CreateVector3()
    	set oYAxis = XSIMath.CreateVector3()
    	set oZAxis = XSIMath.CreateVector3()

    	' Make sure input object is valid
    	if TypeName(InputObjs(0)) <> "X3DObject" then
    		set GetLocalReferenceFrame_Execute = Nothing
    		Application.LogMessage( "Input object is not a valid object: " & InputObj.Type )
    		exit function
    	end if

    	' Decide which info to get
    	if Dimension = 0 then
    		set oXDGeometry = InputObjs(0).Obj.Geometry0D
    	elseif Dimension = 1 then
    		set oXDGeometry = InputObjs(0).Obj.Geometry1D
    	else
    		set oXDGeometry = InputObjs(0).Obj.Geometry2D
    	end if

    	' Call the correct method and then use the output arguments to populate the array to return
    	' In this case we want to return the actual values of the SIVector3, not the SIVector3
    	' itself. This is because the C++ API cannot handle the SIVector3 interface so we need to pass
    	' the actual x,y,z values.
    	oXDGeometry.LocalReferenceFrame i, oXAxis, bXAxisValid, oYAxis, bYAxisValid, oZAxis, bZAxisValid
    	aInfoCollection = Array(	oXAxis.X, oXAxis.Y, oXAxis.Z, bXAxisValid, _
    								oYAxis.X, oYAxis.Y, oYAxis.Z, bYAxisValid, _
    								oZAxis.X, oZAxis.Y, oZAxis.Z, bZAxisValid )

    	' The array returned will be a 1-dimensional SAFEARRAY
    	GetLocalReferenceFrame_Execute = aInfoCollection
    end function

C++ Example: Using the VBS wrapper to get the Local Reference Frame

This example demonstrates how to get the Local Reference Frame information on a cube using the C++ API. Because the C++ API cannot handle the output arguments returned by the LocalReferenceFrame methods on the deprecated Geometry0D, Geometry1D, and Geometry2D objects, you must write a custom command in VBScript to extract the information and reformat it for use by the C++ API. In this example, the expected result is a flat array of 12 elements arranged as 3 quartets of double, double, double, bool elements. Each quartet represents the x.y.z values plus an indicator of the validity for each axis (as implemented in VBScript Example: Implementing a C++ API-compliant version of the LocalReferenceFrame methods).

    	Application app;
    	Model root = app.GetActiveSceneRoot();

    	// Create a cube
    	X3DObject objItem; root.AddGeometry( L"Cube", L"MeshSurface", L"MyCube", objItem );

    	// Get number of vertices in the cube
    	CPointRefArray refPoints = objItem.GetActivePrimitive().GetGeometry().GetPoints();
    	LONG nbrPoints = refPoints.GetCount();

    	// Set up the arguments for the custom command
    	CValueArray ccArgs(3); CValue ccOut;
    	ccArgs[0] = objItem;
    	ccArgs[2] = CValue(0.0);

    	// Get the local reference frame for each point
    	for ( LONG i=0; i<nbrPoints; ++i )
    	{
    		// Run the command (you only need to change the index number for this example)
    		ccArgs[1] = i;
    		app.ExecuteCommand( L"GetLocalReferenceFrame", ccArgs, ccOut );

    		// Grab the output arguments from the returned array
    		if ( ccOut.m_t == CValue::siArray )
    		{
    			MATH::CVector3 vc3XAxis; MATH::CVector3 vc3YAxis; MATH::CVector3 vc3ZAxis;
    			bool booXAxisValid; bool booYAxisValid; bool booZAxisValid;

    			CValueArray aResults(ccOut);
    			vc3XAxis.Set( aResults[0], aResults[1], aResults[2]  ); // XAxis
    			booXAxisValid = aResults[3];								// XAxisValid
    			vc3YAxis.Set( aResults[4], aResults[5], aResults[6]  ); // YAxis
    			booYAxisValid = aResults[7];								// YAxisValid
    			vc3ZAxis.Set( aResults[8], aResults[9], aResults[10]  ); // ZAxis
    			booZAxisValid = aResults[11];								// ZAxisValid

    			// Log the information in Softimage
    			if ( booXAxisValid )
    			{
    				app.LogMessage ( L"Component [" + CString(i) + L"] X axis : " + CString(vc3XAxis.GetX()) + L" | " + CString(vc3XAxis.GetY()) + L" | " + CString(vc3XAxis.GetZ()) );
    			} else {
    				app.LogMessage ( L"Component [" + CString(i) + L"] INVALID X axis" );
    			}

    			if ( booYAxisValid )
    			{
    				app.LogMessage ( L"Component [" + CString(i) + L"] Y axis : " + CString(vc3YAxis.GetX()) + L" | " + CString(vc3YAxis.GetY()) + L" | " + CString(vc3YAxis.GetZ()) );
    			} else {
    				app.LogMessage ( L"Component [" + CString(i) + L"] INVALID Y axis" );
    			}

    			if ( booZAxisValid )
    			{
    				app.LogMessage ( L"Component [" + CString(i) + L"] Z axis : " + CString(vc3ZAxis.GetX()) + L" | " + CString(vc3ZAxis.GetY()) + L" | " + CString(vc3ZAxis.GetZ()) );
    			} else {
    				app.LogMessage ( L"Component [" + CString(i) + L"] INVALID Z axis" );
    			}
    		}

Local Frame Magic Formula

The local reference frame for vertices of polygon meshes is computed in object space, as the following:

- Y = vertex normal This is the same as Geometry0D.Normal or Point.Normal (or Point::GetNormal in the C++ API). To compute it yourself, you have to take the normalized sum of the cross products of the pair of consecutive normalized edge vectors around the vertex.

- X = normalized projection of the first edge vector (starting from current vertex) onto the normal plane.

- Z = cross prod of X and Y.