Vector Product Format (VPF) is a MIL STD database specification for large geographic datasets. The specification is available for download from National Imagery and Mapping Agency (NIMA) at this link . libgeovpf provides a set of GObjects that facilitate drawing information from a VPF database onto the geocanvas.

The only GObject that is strictly required is GeovpfCanvasTheme. This object handles the querying, drawing, and management of a single library, coverage, feature class, and expression combination.

This example creates a simple theme.

/* The GeovpfCanvasTheme is used to display all feature types - edge, face,
 * entity_node, connected_node, and text.
 *
 * library_path: location of the library.  Use of directory path can be avoided
 * by using the GeovpfDatabaseLookup object.
 *
 * coverage: a set of topologically related feature classes.  Earth coverage in
 *              in this case.
 *
 * feature_class: features that share a homogenous set of attributes.  Earth
 *              coverage areas in this case.
 *
 * expression: thematic information (a limited database query).  
 *             This example queries for land and island coverage.
 */
foo_canvas_item_new(group, GEOVPF_TYPE_CANVAS_THEME,
        "library_path", "/home/username/dnc/dnc17/a1707420",
        "coverage", "ecr",
        "feature_class", "ecrarea",
        "expression", "F_CODE=BA030 or F_CODE=DA010",
        "fill_color_rgba", 0xBDAF1Bff,
        NULL);

The VPF database structure looks something like this:

        Database (e.g. DNC17)
                - Library (e.g. a1707420 approach chart)
                        - coverage (e.g. ecr)
                                - feature class (e.g. ecrarea)
                                        -expression (e.g. F_CODE, etc.)

To discover how to properly set up the coverage, feature class, and expression properties of the theme, there is a program included in the geovpf directory of this package called geovpfprint. Use the -h option to see the usage. This program can provide a detailed list of what is available in the for the VPF databases being used.

The use of a directory path in the "library_path" property is not required if the GeovpfDatabasLookup is used. A VPF database can consist of 100 or more libraries. In some cases it might be necessary to browse through multiple databases. The GeovpfDatabaseLookup object simplifies finding the a library by building a hash table at construction time. It builds the has table based on a pre-defined colon delimited directory search path. When the GeovpfDatabaseLookup object has been initialized, it is necessary only to specify the library_name to the theme.

Here is the example again using the GeovpfDatabaseLookup

/* The database lookup is a singleton object.  The directory search path is
 * is colon delimited.
 */
g_object_new(GEOVPF_TYPE_DATABASE_LOOKUP, "search_path",
        "/home/username/dnc:/mnt/cdrom", NULL);

foo_canvas_item_new(group, GEOVPF_TYPE_CANVAS_THEME,
        "library_path", "a1707420",
        "coverage", "ecr",
        "feature_class", "ecrarea",
        "expression", "F_CODE=BA030 or F_CODE=DA010",
        "fill_color_rgba", 0xBDAF1Bff,
        NULL);

To simplify things even further, it is possible to not use the "library_path" property at all. The GeovpfLibrarySelector and GeovpfCanvasView objects can be used to partially automate the selection of the appropriate library. The GeovpfLibrarySelector can be used to determine the list of libraries from the database search path that fit the current GeoCanvas viewport. It connects to the GeoCanvas viewport-changed signal. Whenever the viewport changes, it searches the list of available libraries from the GeovpfDatabaseLookup object and reports the subset that is equal or larger in size and location to current viewport.

Each time the viewport changes, GeovpfLibrarySelector emits three signals. The first signal, the select-event, indicates that a library is available for selection. This event is emitted once for each of the available libraries until a listener returns a TRUE value. If a TRUE value is returned, that library is marked to be selected, otherwise the library at the head of the list is marked. The second signal is a notify on the available_libraries property. The available _libraries is a linked list of all libraries that fit the current viewport. Finally, a notify is issued on the selected_library property if it is different than the proeviously selected library.

The GeovpfCanvasView object is a simple canvas group that connects to the GeovpfCanvasSelector. It has special logic to select an appropriate library based on its library_pattern property and pass the library_name into is child GeovpfCanvasTheme objects. A GeovpfCanvasView can be thought of as a set of themes that should be applied to specific type of library.

Here is an example of how to use the GeovpfCanvasView:

        /* The library selector needs to be told which canvas to connect to.
        * After that, all views will look for a singleton instance unless the
        * view "library-selector" property is set explicitly.
        */
        selector = g_object_new(GEOVPF_TYPE_LIBRARY_SELECTOR, "geocanvas",
                        FOO_CANVAS_ITEM(group)->canvas, NULL);
                        
        /* This view will activate select any library that begins with "g".
         * DNC, this is a "general" library.
         */
        general = FOO_CANVAS_GROUP(
                foo_canvas_item_new(group, GEOVPF_TYPE_CANVAS_VIEW,
                        "library_pattern", "g*", 
                        NULL));

        /* This item will draw water */
        foo_canvas_item_new(general, GEOVPF_TYPE_CANVAS_THEME, 
                "coverage", "ecr", 
                "feature_class", "ecrarea",
                "expression", "F_CODE=BA040",
                "fill_color_rgba", 0xD1F4FFFF,
                NULL);
        /* This item will draw mainland and islands */
        foo_canvas_item_new(general, GEOVPF_TYPE_CANVAS_THEME, 
                "coverage", "ecr", 
                "feature_class", "ecrarea",
                "expression", "F_CODE=BA030 or F_CODE=DA010",
                "fill_color_rgba", 0xBDAF1Bff,
                NULL);
        /* This item will draw text features. */
        foo_canvas_item_new(general, GEOVPF_TYPE_CANVAS_THEME,
                "coverage", "ecr",
                "feature_class", "ecrtext",
                "fill_color_rgba", 0x000000FF,
                NULL);