Manifold APIs

All APIs - Object model for .NET / COM

Contents

1. Overview
1.1. .NET / COM languages
1.2. The Root object and third-party applications
1.3. The Context object
1.4. The Application object
2. Root
2.1. Root constructor
2.2. Root.Application
3. Context
3.1. Context.Application
4. Application
4.1. Application.CreateDatabase
4.2. Application.CreateDatabaseForFile
4.3. Application.CreateGeomBuilder
4.4. Application.CreateTileBuilder
4.5. Application.CreateTable
4.6. Application.GetDatabaseRoot
4.7. Application.Log
4.8. Application.MessageBox
4.9. Application.Name
4.10. Application.OpenLog

1. Overview

1.1. .NET / COM languages

The object model for .NET / COM is designed to work with all .NET languages, including dynamic ones, and with COM languages accessible via active scripting APIs. COM languages use the object model through COM wrappers for .NET objects automatically generated by the system.

The Radian application includes explicit support for the following languages:

Third-party applications may use other .NET or COM languages.

Example code in this document uses C# unless specified otherwise.

The required version of .NET is 4+, .NET 2 / 3 / 3.5 are not supported.

1.2. The Root object and third-party applications

The Root object is used to start and initialize the object model from a third-party application.

A third-party application using the object model for .NET / COM usually includes an instance of EXTNET.DLL which contains the implementation of the Root object. At runtime, the application creates an instance of that object, starting the object model. If the object model starts successfully, the application can access the Root.Application property of the Root object. That returns the Application object used to access the rest of the object model.

The constructor of the Root object takes a string parameter with an optional path to EXT.DLL which contains the implementation of the object model. The application can use that path to choose between multiple installed builds of Radian on the same system, or to specify the location of the portable install of Radian if there is no non-portable install. If the path is left empty, the Root object will try to locate EXT.DLL in the default installation path automatically.

1.3. The Context object

The Context object represents the running context of a script. There might be multiple scripts running at the same time, each of these scripts gets its own instance of the Context object.

.NET scripts access the Context object representing their running context via a shared 'Manifold' property of the pre-defined 'Script' class that they declare.

Example .NET script:

// C#

class Script
{

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application.Log("Hello, World!");
    Manifold.Application.OpenLog();
}

}

COM scripts access the Context object representing their running context via a global variable named 'Manifold'.

Example COM script:

' VBScript

Sub Main
    Manifold.Application.Log "Hello, World!"
    Manifold.Application.OpenLog
End Sub

A running script can access the Context.Application property of the Context object. That returns the Application object used to access the rest of the object model.

1.4. The Application object

The Application object provides access to the rest of the object model.

The Application object allows creating and opening new databases, accessing the root database which represents the 'main' database for the object model, creating new in-memory tables. It also allows creating helper objects like GeomBuilder and TileBuilder, and provides various global functions such as Application.Log.

2. Root

2.1. Root constructor

Syntax

Root(string path)

Parameters

path - path to EXT.DLL. May be empty.

Notes

Creating an instance of the object attempts to start and initialize the object model.

If path is a non-empty string, the object will attempt to use EXT.DLL in the specified location. If path is an empty string, the object will try to use EXT.DLL in the default installation path:

C:\Program Files\Manifold\v9.0\Bin, if the application attempting to create an instance of the object is 32-bit,

C:\Program Files\Manifold\v9.0\Bin64, if the application attempting to create an instance of the object is 64-bit.

If the object model fails to initialize, attempting to create an instance of the object will throw an exception.

2.2. Root.Application

Syntax

Application Application

Return Value

Returns an Application object for the initialized object model.

3. Context

3.1. Context.Application

Syntax

Application Application

Return Value

Returns an Application object.

4. Application

4.1. Application.CreateDatabase

Syntax

Database CreateDatabase()
Database CreateDatabase(string technology, string connection, bool forceDiscover)

Parameters

technology - technology name, eg, 'map'. Case-insensitive.

connection - connection string.

forceDiscover - if true, forces the database to completely finish discovery of all available components before the call returns; if false, the database will discover available components progressively in a background thread after the call returns.

Return Value

Returns a Database object.

If forceDiscover is true, Database.Search is guaranteed to return data for any of the available components, and the mfd_root table lists all available components as well.

If forceDiscover is false, the call finishes faster with the discovery process offloaded to a background thread, but Database.Search may fail to return data for some of the available components until they are discovered, and mfd_root will not list them until they are discovered either.

Notes

Calling the method without parameters creates a new in-memory MAP file.

Calling the method with parameters creates a database for the specified technology and connection string. The forceDiscover parameter should normally be set to true, unless the caller wants to reduce the time it takes to connect to the database and is prepared to deal with the components being discovered progressively in a background thread (for example, is prepared to wait until the discovery completes in case the requested component is not yet available).

Database objects are expensive. It is best to dispose them immediately after they are no longer needed.

Examples

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application app = Manifold.Application;
    using (Manifold.Database db = app.CreateDatabase())
    {
        Manifold.Table meta = db.Search("mfd_meta");
        Manifold.Schema metaSchema = meta.GetSchema();
        app.Log(metaSchema.Fields.Count.ToString() + " fields");
    }
    app.OpenLog();
}
// result: 4 fields

The above example creates a new in-memory MAP file, finds the mfd_meta table inside that MAP file and reports the number of fields in that table.

Note that the created Database object is used with 'using', to automatically dispose it and reclaim the memory it uses at the earliest moment possible.

static Manifold.Context Manifold;
static void Main()
{
    string tech = "imgerdas";
    string conn = "{ \"Source\":\"c:\\\\data\\\\example.img\" }";
    Manifold.Application app = Manifold.Application;
    using (Manifold.Database db = app.CreateDatabase(tech, conn, true))
    {
        Manifold.Table tiles = db.Search("example tiles");
        app.Log("accessed image data");
    }
    app.OpenLog();
}
// result: accessed image data

The above example connects to an existing ERDAS IMG file named c:\data\example.img and retrieves the table that contains image data.

Note that the backslashes in the connection string are doubled twice - first for the C# compiler which converts every pair of backslashes in a string value into one backslash, and second for the connection string parser which converts every pair of backslashes in a JSON string value into one backslash.

The value of the connection string seen by the method is:

{ "Source":"c:\\data\\example.img" }

4.2. Application.CreateDatabaseForFile

Syntax

Database CreateDatabaseForFile(string path, bool forceDiscover)

Parameters

path - path to file, eg, 'c:\data.csv'.

forceDiscover - if true, forces the database to completely finish discovery of all available components before the call returns; if false, the database will discover available components progressively in a background thread after the call returns.

Return Value

Returns a Database object.

If forceDiscover is true, Database.Search is guaranteed to return data for any of the available components, and the mfd_root table lists all available components as well.

If forceDiscover is false, the call finishes faster with the discovery process offloaded to a background thread, but Database.Search may fail to return data for some of the available components until they are discovered, and mfd_root will not list them until they are discovered either.

Notes

The method attempts to automatically determine connection technology from the specified path. The method first analyzes the filename. If the filename matches more than one technology (for example, the file named 'A.NTF' could be an NTF file or a NITF file), the method attempts to determine the technology from the file contents.

Database objects are expensive. It is best to dispose them immediately after they are no longer needed.

Examples

static Manifold.Context Manifold;
static void Main()
{
    string path = "c:\\data\\example.img";
    Manifold.Application app = Manifold.Application;
    using (Manifold.Database db = app.CreateDatabaseForFile(path, true))
    {
        Manifold.Table tiles = db.Search("example tiles");
        app.Log("accessed image data");
    }
    app.OpenLog();
}

The above example connects to an existing ERDAS IMG file named c:\data\example.img and retrieves the table that contains image data.

4.3. Application.CreateGeomBuilder

Syntax

GeomBuilder CreateGeomBuilder()

Return Value

Returns a GeomBuilder object used to create geometry values.

Notes

A single GeomBuilder object can be used to create any number of geometry values. There is no need to create a new builder object for each new desired value.

Examples

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application app = Manifold.Application;
    Manifold.Geom geom;
    {
        Manifold.GeomBuilder builder = app.CreateGeomBuilder();
        builder.StartGeomPoint(); // allows multipoint
        builder.AddBranch();
        builder.AddCoord(new Manifold.Point<double>(3, 4));
        builder.AddCoord(new Manifold.Point<double>(5, 6));
        builder.EndBranch();
        geom = builder.EndGeom();
    }
    app.Log(geom.Coords.Count.ToString());
    app.OpenLog();
}
// result: 2

The above example builds a new geometry value and reports the number of its coordinates.

4.4. Application.CreateTileBuilder

Syntax

TileBuilder CreateTileBuilder()

Return Value

Returns a TileBuilder object used to create tile values.

Notes

A single TileBuilder object can be used to create any number of tile values. There is no need to create a new builder object for each new desired value.

Examples

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application app = Manifold.Application;
    Manifold.Tile tile;
    {
        Manifold.TileBuilder builder = app.CreateTileBuilder();
        builder.StartTile(2, 2, "uint8");
        builder.Pixels[0, 0] = (byte)5;
        builder.Pixels[0, 1] = (byte)6;
        builder.Pixels[1, 0] = (byte)7;
        builder.Pixels[1, 1] = (byte)8;
        tile = builder.EndTile();
    }
    app.Log(tile.Pixels[1, 1].ToString());
    app.OpenLog();
}
// result: 8

The above example builds a new tile value and reports the value of one of its pixels.

Note that setting pixel values requires conversion to the correct type.

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application app = Manifold.Application;
    Manifold.Tile tile;
    {
        Manifold.TileBuilder builder = app.CreateTileBuilder();
        builder.StartTile(3, 1, "uint8x3");
        builder.Pixels[0, 0] = new Manifold.Point3<byte>(1, 2, 3);
        builder.Pixels[1, 0] = new Manifold.Point3<byte>(4, 5, 6);
        builder.Pixels[2, 0] = new Manifold.Point3<byte>(7, 8, 9);
        tile = builder.EndTile();
    }
    app.Log(((Manifold.Point3<byte>)tile.Pixels[2, 0]).X.ToString());
    app.OpenLog();
}
// result: 7

The above example builds a new tile with multiple channels and reports the value of one channel in one of the pixels.

4.5. Application.CreateTable

Syntax

Table CreateTable()

Return Value

Returns a Table object for a new in-memory table.

Notes

The returned table contains default fields and indexes, the table schema can be altered using Table.Design. The table supports reading and writing records, the limitations are the same as for tables in a MAP file.

In-memory tables are used to temporarily store data in a structured format.

Table objects are expensive. It is best to dispose them immediately after they are no longer needed.

Examples

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application app = Manifold.Application;
    using (Manifold.Table table = app.CreateTable())
    {
        Manifold.Schema schema = table.GetSchema();
        app.Log("Fields in new table:");
        foreach (Manifold.Schema.Field field in schema.Fields)
            app.Log(field.Name);
    }
    app.OpenLog();
}
// result: Fields in new table
// ....... mfd_id

The above example creates a new in-memory table and lists its fields.

4.6. Application.GetDatabaseRoot

Syntax

Database GetDatabaseRoot()

Return Value

Returns a Database object for the 'main' database for the object model.

Notes

If the method is called in the context of the Radian application, it returns the currently opened MAP file.

Database objects are expensive. It is best to dispose them immediately after they are no longer needed.

Examples

// in a script component named 'Script'

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application app = Manifold.Application;
    using (Manifold.Database db = app.GetDatabaseRoot())
    {
        app.Log("Existing components");
        using (Manifold.Table table = db.Search("mfd_root"))
        {
            string[] fields = new string[] { "Name" };
            using (Manifold.Sequence sequence = table.SearchAll(fields))
            {
                while (sequence.Fetch())
                    app.Log(sequence.GetValues()[0].Data.ToString());
            }
        }
    }
    app.OpenLog();
}
// result: Existing components
// ......: mfd_root
// ......: mfd_meta
// ......: Script

The above example lists all components in the currently opened MAP file in the Radian application.

4.7. Application.Log

Syntax

Log(string text)

Parameters

text - text message.

Notes

The method appends the specified text message to the log.

If the text message is empty, the call is ignored.

Leading whitespace is preserved. Trailing whitespace is trimmed. Multiline text messages are split into different log lines.

Log lines generated by a script appear with the '++' type prefix.

Example

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application app = Manifold.Application;
    app.Log(""); // ignored
    app.Log("   leading whitespace");
    app.Log("trailing whitespace \r\n");
    app.Log("multiple\r\nlines");
    app.OpenLog();
}
// result:    leading whitespace
// ....... trailing whitespace
// ....... multiple
// ....... lines

The above example illustrates the handling of whitespace and line breaks.

4.8. Application.MessageBox

Syntax

MessageBox(string text, string caption)

Parameters

text - text message.

caption - caption.

Notes

The method displays a message box with the specified text and caption.

If caption is an empty string, the method will use the default caption.

Example

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application app = Manifold.Application;
    app.MessageBox("Message text", "Caption");
}

The above example displays a message box with custom text and caption.

4.9. Application.Name

Syntax

string Name

Return Value

Returns the name of the object model application, such as 'Radian Studio'.

Example

static Manifold.Context Manifold;
static void Main()
{
    Manifold.Application app = Manifold.Application;
    app.Log(app.Name);
    app.OpenLog();
}
// result: Radian Studio

The above example appends the name of the object model application to the log.

4.10. Application.OpenLog

Syntax

OpenLog()

Notes

If the method is called in the context of the Radian application, it opens the log window. Otherwise, the method does nothing.