project - Programmatically access and manipulate a project

Name

project — Programmatically access and manipulate a project

Syntax

Description

The project command is used to programmatically access and manipulate a Geocap project.

Object Path

The project command frequently uses a path designation to address the project object to which the command should apply. The path argument is typically an object name, possibly prepended by the folders containing the object. The structure of the path argument is similar to that used in file systems.

The path argument comes in two different flavors, relative and absolute. The absolute path may also provide the name of the project on which to operate.

Relative Path

The relative path is simply the name of the object in question. The lookup is performed relative to the active project object, which can be set with project activate or project setpath. The object name should be provided as a plain string, not a Tcl list.

The following example uses the project exists command to see if the folder named MyFolder contains an object named "My Data". The "My Data" argument is provided without any parent folder or project reference, and is therefore considered to be relative.

# Set the top-level folder MyFolder to be the active object
# The argument to 'setpath' is an absolute path, since it contains an initial root token '/'
project setpath {  / MyFolder } ;

# Sees if "My Data" exists as a child of MyFolder. Relative lookup is used.
set exists [project exists "My Data"]

Absolute Path

An absolute path is a Tcl list containing the name of the target object and its parent folders. The first element may be the name of a project. The list will also have the root symbol '/' preceeding the folder names.

# Make MyFolder in the current project the active object
project setpath { / MyFolder }

# Address the MyFolder object in a different project called "North Sea"
project setpath {  "North Sea" / MyFolder }

Note that the project path command returns an absolute path as a Tcl list. This can be used as-is with the corresponding project setpath command.

Arguments

activate projectname name1 name2...

Sets the active project object. Most project command operate The active project object plays a central role when using the project command, since many project subcommands operate implicitly on this object.

The arguments given to this command are the components in the path that identifies the object in the project tree. The format is equivalent to the path format described in Object Path, except that the path components are not combined into a list.

As a special case, omitting the path argument altogether makes the current project root the active project object. The root object, while not visible in the project tree, is the parent of the toplevel objects.

Example: Activating a project object

Given the following project layout :

To make the object "iso 2" the active object :

project activate / Zones "iso 2"

The arguments "/ Zones 'iso 2'" constitute the path to the new active project object. The first element '/' in the path is the root symbol, which tells Geocap to start the lookup traversal at the top of the object hierarchy. A path need not be absolute, ie. need not start with a root symbol. The lookup is then initiated relative to the current active object :

project activate / Zones	; # Make Zones active
project activate "iso 2"	; # Make "iso 2" active, relative path

To make the root object the active object simply omit the path arguments

project activate        ; # Make root the active object
project activate Zones  ; # Goto "Zones", relative path OK

The previous examples assumed that the new active object was present in the active project. To activate an object in an abitrary project simply prepend the project name to the object path, seperating the two with '/'. The following example activates the 'Dataset' object in the MyProject project.

 project activate MyProject / Zones Dataset

Note that when explicitly specifying the project, as in the previous example, the rest of the path is assumed to be absolute.

See also project setpath.

browse [typenames]

Displays a project browser and returns a Tcl list containing the path to the object selected by the user. The path is absolute, containing the project name as the first element, see Object Path for a description. If the user presses "Cancel" an empty string is returned. You may provide a sequence of type names to filter the type of objects that will be displayed. Note that the type of the parent objects will have to be included as well.

Example: project browse

The following snippet creates a project browser and checks the result to see if the user pressed "Cancel" :

set o [project browse]
if { $o == "" } {
  return ;              # Cancel
} else {
  project setpath $o ;  # Activate selected object
}

To see only poly data you can provide type names to the browse argument.

set o [project browse category_generic vtk_poly_data]
if { $o == "" } {
  return ;              # Cancel
} else {
  project setpath $o ;  # Activate selected object
}

See also project setpath on how to set the browse result object to be the active object. See project browse in order to browse multiple objects.

category

The project category command returns the name of the category to which the active object belongs. It is an error if the active object is not a category. The category name is formatted in the same manner as used by the project view.

Example: category

set catname [project category]
if { $catname == "Wells" } { ... }

children [typenames]

To get all the children of the active object into a Tcl list. If any type names are supplied as arguments, only children of the given types will be listed.

Example: project children

To get all children of the active object:

set childlist [project children]
# To get the first child
set child [lindex $childlist 0]
message "child: $child"

commit

Saves the project and flushes memory.

copy

Copies the active project object to the clipboard. This is not the clipboard used by the operating system

cut

Cuts the active project object to the clipboard. This is not the clipboard used by the operating system.

The object will exist in the project until a paste operation is performed.

create type name

The project create command creates an object in the current project, making it the new active object. The new object's type and name are supplied as arguments. The object's parent will be the object that is active at the time of creation. If the active object is null, the new object will be a toplevel object.

Example: project create

Assuming we are starting out with an empty project, creating an empty dataset object in a folder could be done as follows :

project activate                              ; # Go to root
project create category_generic "My polygons" ; # Create toplevel folder, becomes active object
project create vtk_poly_data "My line"        ; # Create empty data object as child of folder, becomes active object
project setdata                               ; # Assign data from Geocap's workspace

The comments describe how each newly created object in turn is made the active object. The object layout would then become :

To create several objects with a common parent make sure the previous active object is reset after object creation. To create two polygon objects, for example :

project activate                              ; # Go to root
project create category_generic "My polygons" ; # Create toplevel folder, becomes active object
project create vtk_poly_data "My line"        ; # Create empty data object as child of folder, becomes active object
project up                                    ; # Reset folder as active object (parent)
project create vtk_poly_data "My line 2"      ; # Another data object

delete

Deletes the active object, making the object's parent the new active object. Any children the object may have are deleted as well.

deletechildren [typenames]

Deletes the children of the active object. If any type names are supplied as arguments, only children of the given types will be deleted.

Example: project deletechildren

To delete all children of the active object:

project deletechildren

To delete only poly data and structured points:

 project deletechildren vtk_poly_data vtk_structured_points

execscript script [name] [path]

Executes script commands either on the active project object or, if given, the target object path. Geocap will create and execute a temporary script command object on the target object. Any graphics created during the execution will be collected as actor icons in the usual manner. This command thus mimics the conventional interactive execution of command objects. Note that if path is provided the name argument is required too.

Example: Directly executing script commands on project objects

The following example assumes that a project called "Coasts" has been loaded into Geocap. Various invocations show different uses of the available arguments. The comments provide details of the particular syntax used in each example.

project activate / Generic Denmark   ; # Activate the 'Denmark' dataset
project execscript dis    ; # Executes the command 'dis' on Denmark, assumed to be the active project object
project execscript dis "Danish Coastline" ; # As above, but assigns the name "Danish Coastline" to the actor item

project activate / Generic    ; # Activate the 'Generic' folder
project execscript { z ; dis } "Danish Coastline" Denmark ; # Path 'Denmark' used relative to the 'Generic' folder

# Absolute path, no activate necessary
project execscript { z ; dis } "Coast" { / Generic Greenland }

# Absolute path with project name, useful if multiple projects are loaded. No activate necessary
project execscript { z ; dis } "Coast" { Coasts / Generic Greenland }

execshared sharedcommand

Executes given shared command attached to the current project object.

Example: Executing a shared command

project activate / Generic mydataset
project execshared "Display Points" ; # Execute shared command "Display  Points" on mydataset

execute objectcommand

Executes given object command attached to the current project object.

Example: Executing an object command

project activate / Generic mydataset
project execute "Display Points" ; # Display points in mydataset

exists path

The project exists command returns 1 if the named object exists, or 0 if the object does not exist. The path argument may be relative or absolute according to the description in Object Path.

Example: project exists

# Absolute path
if { [project exists { / MyFolder "MyData"} ] } {
    puts "Object exists"
}

# Relative path
project activate / MyFolder
if { [project exists "MyData"] } {
    puts "Object exists"
}

filename

Returns the filename of the current project as an absolute path.

flushcacheonoverflow

Force the project to free memory if the amount of memory used exceeds the preset cache size. If the amount of used memory is less than the cache size no action is performed.

See project setcachesize, project getcachesize, project memorysize.

foreach [types] cmds

The project foreach command iterates through the first level children of the active object. Each visited child is made the active object while the commands supplied as the last argument is executed. When the traversal is finished, the active object from the start of the traversal is restored. If one or more typenames are given as arguments, only children of those types will be traversed.

Example: Using foreach

Given the following project layout :

To print out all items underneath "Surfaces" we would write as follows :

project activate / Surfaces
project foreach {
    message [project getname]
}

If we wanted to traverse only surfaces, we would supply the "surface" type name as an argument :

 project activate / Surfaces
project foreach vtk_poly_data {
   message [project getname]
}

When the traversal is finished, the "Surfaces" folder is again the active object.

getdata

The project getdata command copies the vtk dataset held by the active object to Geocaps workspace, making it the active dataset. This requires that the active object be able to receive a dataset. Use the project setdata command to transfer data the other way, that is, assigning Geocap's active dataset to the active project object.

Example: Transferring project data to workspace

Given the following object layout :

The following command makes the surface "munin 1" the active dataset in Geocap :

project activate / Surfaces "munin 1"
project getdata

getname

The project getname command returns the name of the active object.

Example: Get name of project object

set name [project getname]

getprop key

The project getprop command returns the value of the property named key in the active object. Attempting to read a non-existing value returns a null object.

See project setprop for an example.

getschema

Returns schema name for the active object.

getscript

Returns the script associated with the active object. This requires the active object to be of type script.

See project setscript on how to assign a script.

gettext

Returns the text associated with the active object. This requires the active object to be of type text.

See project settext on how to assign textual content to a text object.

getvtkref

Return a reference to the active object's vtk dataset as a Tcl variable

Example: Assign project data to Tcl variable

Given the following project layout:

The following example shows how to assign project data to a Tcl variable, then use that variable to assign a copy of the data to a different folder in the project.

# Read data
project activate / Generic mydata
set vtkdata [project getvtkref]

# Copy data into new folder
project activate /
project create category_generic "New Folder"
project create vtk_structured_points "New Data"

project setdatacopy $vtkdata

The final statement could have used project setdata instead of project setdatacopy. However, then the source and target object would have shared the same underlying vtk dataset, which may not be what you want.

See also project setdatacopy.

memorysize

Returns the amount of memory used by the project, in kilobytes.

See project flushcacheonoverflow, project setcachesize, project getcachesize.

isnull

Returns 1 (true) if the active object is null, else 0.

listmodified

Lists modified objects in the message window and returns the object paths as a list. Since each path is itself a list the return value is a list of lists.

multibrowse [path]

Browse multiple project objects, returning a list of paths. The initial folder will be determined from the path argument, or the current active object if this argument is not provided. If the initial object is not a folder its parents are traversed until a folder is found.

The browse dialog lets you filter items by name.

set paths [ project multibrowse]
foreach path $paths {
	project setpath $path
	# ....
}

See also project browse and project singlebrowse.

singlebrowse [path]

Browse project objects, returning the path of the selected object. If no object is selected an empty string is returned. The initial folder will be determined from the path argument, or the current active object if this argument is not provided. If the initial object is not a folder its parents are traversed until a folder is found.

The browse dialog lets you filter items by name.

set path [ project singlebrowse "Generic"]

See also project browse and project multibrowse.

new filename [projectname]

Creates a new project. If projectname is not provided the last part of the filename is used.

open filename

Opens a project. The filename argument points to the project's .db file.

paste

Pastes the project object in the clipboard into the project as child of the current object.

path

The project path command returns a Tcl list containing the name of the current project and the path components of the active project object. The format is described in Object Path.

The path list returned from project path is equivalent to the path argument accepted by project setpath.

{ projectname / c1 c2 ... }

In the previous example c1 c2 ... are path components. For example, c1 could be a folder name, and c2 the name of one of its children.

Example: Get path of project object

Given the following project layout with "iso 2" as the active object :

Executing the following code will display the path in Geocap's message window:

 puts [project path]

The output MyProject / Zones 'iso 2' should then be visible in the message window, where MyProject is the name of the project. Note that the enclosing braces {} are omitted in the message window.

See also project setpath.

projectname [name]

Gets or sets the project name. If name is not provided the project name is returned.

projectnames

Returns the names of all projects currently loaded.

save

Saves the current project.

getcachesize [cache size in kilobytes]

Return the project cache size in kilobytes.

See project flushcacheonoverflow, project setcachesize, project memorysize.

setcachesize [cache size in kilobytes]

Set the project cache size in kilobytes.

See project flushcacheonoverflow, project getcachesize, project memorysize.

setcreatedata path [name]

The project setcreatedata command copies Geocap's active dataset to the project. The path is a Tcl list denoting the target location for the dataset. If the target is a folder, a new dataobject will be created as a child of the folder. If the target is itself a dataobject, it's dataset will be replaced by the incoming active data.

The resulting dataobject will either take the final name argument as name, or retain it's original name 'active' if this argument is omitted.

Example: setcreatedata example

Given the following project layout:

The user may wish to copy the active dataset to the folder 'Surfaces', giving it the name 'grid':

project setcreatedata {  / Surfaces } grid

Alternatively, the user may wish to replace the data contents of "munin 1" with the active data:

project setcreatedata {  / Surfaces } "munin 1"

setcurrent [projectname]

Sets the current project. Subsequent project commands will apply to the new current project.

setdata workspacedata

The project setdata command assigns a vtk dataset to the active project object. This requires the active object to be able to contain a dataset. The target object is commonly a vtk_poly_data or vtk_structured_points object. If the target object does not exist, use project create to create a one.

Which dataset is assigned depends on the syntax used. If no argument is provided, the data to be assigned is taken to be Geocap's active dataset. Alternatively, a Tcl variable containing a vtk dataset may be passed as an argument. Tcl variables that contain vtk data are typically the result of using the project getvtkref command.

Example: Assigning data to project object

Given the following object layout :

The user may wish to update "munin 1" with the dataset currently active in Geocap :

project activate / Surfaces "munin 1"
project setdata

If the user wishes to keep "munin 1" and assign Geocap's active data to a new project object, she would first create the object using the project createcommand. Note that the new object's parent, the "Surfaces" folder, is made the active object prior to object creation :

project activate / Surfaces ;			# Will become parent of new object
project create vtk_poly_data "munin 3"	       ;# Create empty surface object
project setdata				       ;# Assign data

The new surface object would then appear in the "Surfaces" folder :

setdatacopy workspacedata

This command is similar to project setdata, but differs in that the dataset is copied before it is assigned to the target project object. This means that the project object will not share the dataset with the source, which, depending on the syntax used, is either Geocap's active data or a Tcl variable. Usingproject setdatacopy instead of project setdata requires more memory, since a duplicate version of the dataset is created. However, detaching the dataset in this way insulates it from accidental modification that may result from modifying the source.

setname name

The project setname command sets the name of the active object. The new name will immediately be visible in the project view.

Example: Setting the name of active project object

project setname "My surface"

setpath path

The project setpath command activates the object referred to in the path argument. This command differs from project activate in that the path argument is a Tcl list, the list elements being the components of the path. The project setpath command works well with project path, which returns the current path as a Tcl list. In particular the following statement will always leave the active object unchanged :

Example: setpath example

project setpath [project path]

The project browse command also returns a path and should be used together with project setpath.

Example 47. project setpath

Given the following project layout :

The following command will make "iso 2" the active object :

project setpath { / Zones "iso 2" }

Enclosing a list of elements in braces is the usual way lists in Tcl are created.

You may prepend the project name before the root token '/'. This is required whenever the path refers to an object in a different project then the current one. The following example activates the "iso 2" object in the MyProject project:

project setpath { MyProject / Zones "iso 2" }

See also project activate and project path.

setprop key value

The project setprop command sets a named property in the active object. A named property is a (key, value) pair, both of which must be convertible to strings. A project object may have any number of named properties, although at most one with a given key can exist at a time. Assigning an already existing property will replace the previous one.

Assigning key, value pairs to an object bears no operational significance on the project behaviour. It is provided as a method for the user to assign his own attributes to project objects. Also, editing a command object allows you to filter execution and visibility depending on properties.

Example: Setting an object property

Assume that the user wishes to store the UTM zone and a version number for the active object. Calling these properties "utm-zone" and "version" she may proceed as follows :

project setprop "utm-zone" 31
project setprop "version" 1.3

When the user wishes to read properties back from an object, she will use the project getprop command :

set uzone [project getprop utm-zone]
set v [project getprop version]

setschema schemaname

Sets schema for the active object.

setscript script

Assigns a script to the active project object, which is required to be of type script. The script argument is simply the textual content of the script.

Example: Assigning a script

# Active the folder Script
project setpath { / Scripts }

# Create a script object
project create script "My Script"

# Assign script contents
project setscript "puts hello"

See project getscript for information on how to retrieve the contents of a script object.

settext text

Assigns text to the active project object, which is required to be of type text.

Example: Assigning text

# Active the folder 'Text'
project setpath { / Text }

# Create a text object called "My Text"
project create text "My Text"

# Assign contents
project settext "Hello world!"

See project gettext for information on how to retrieve the text contained in a text object.

setvtkfile filename

Assigns a vtk file link to the active project object. The active object must belong to the group of types that hold a single vtk dataset. The file will be read, but never written to. Using a file link is an alternative to embedding the vtk dataset into the project, and faciliates sharing of vtk data between different objects. NOTE : Copying the object will only copy the link, not the file itself. Also, the file will not be embedded into an exported project.

Example: Assign vtk file link

project activate my_grid
project setvtkfile "c:/myfile.vtk"

type

The project type command returns the type of the active object. This is the built-in type name, which differs slightly from the formatted version visible in the interface. Built-in type names are all lower-case, with underscore separating the words. Also, some grouping indentifiers like vtk and category are removed. This converts built-in typenames like category_generic to Generic, vtk_poly_data to PolyData etc.

Example: Get the type of the active project object

set type [project type]
if { $type == "vtk_poly_data" } { ... }

up

Activates the parent of the active object, ie. making it the active project object.