FBMEXTRACT

Description

FBMEXTRACT extracts features and descriptors from images for feature-based matching. The extracted features are written to a feature database (FDB) file for use as input with the FBMTIE algorithm.

Parameters

fbmextract(fili, fdbdir, dbic, olevels, keypts, dbiw, loclmask, memsize)

Name	Type	Caption	Length	Value range
FILI *	str	Image file to process	1 -
FDBDIR	str	Output folder for extracted feature database file	0 -
DBIC *	List[int]	Input channel to extract features from	1 - 1
OLEVELS	List[int]	List of downsample levels for feature extraction	0 - 8	Default: 1
KEYPTS	List[int]	Maximum number of key points	0 -	0 - Default: 2000
DBIW	List[int]	Raster input window	0 - 4	Xoffset, Yoffset, Xsize, Ysize
LOCLMASK	str	Local exclusion mask	0 -	Default: NONE
MEMSIZE	List[int]	Working memory size	0 - 1	Default: 512

* Required parameter

Parameter descriptions

FILI

The image file to process.

The algorithm will be fastest when the file consists of 8-bit raster data. Other data types will be temporarily converted to the appropriate data range, with a slight increase in processing time.

FDBDIR

The path and name of the folder to which to write the extracted feature database (FDB) file.

If the folder does not already exist, it will be created automatically.

If you do not specify a value, the FDB file will be written to the same folder as the input image file.

DBIC

The input channel from which to extract features.

OLEVELS

The list of downsample levels for feature extraction.

If the requested downsample levels are available as overviews in the file, the overviews will be used to speed up processing. Otherwise, the requested downsample levels will be automatically computed in a temporary file during processing.

Note: If the overviews do not exist, you can create them by running the PYRAMID algorithm.

KEYPTS

The maximum number of key points to extract per image at each downsample level.

The actual number of extracted key points may differ due to a lack of features in the image or because of the minimum numbers of key points enforced to improve the distribution, match-ability, or both.

DBIW

The raster window (Xoffset, Yoffset, Xsize, Ysize) that is read from the input layers.

Xoffset, Yoffset define the upper-left starting pixel coordinates of the window. Xsize is the number of pixels that define the window width. Ysize is the number of lines that define the window height.

If you do not specify a value for this parameter, the entire layer is processed by default.

LOCLMASK

The local mask to apply that prevents points from being collected in the designated locations.

If you do not specify a value for this parameter (default), or if you specify a value, but one or more of the source images do not contain a bitmap or vector segment, a local exclusion mask will not be applied to the images.

The syntax for LOCLMASK is:

LOCLMASK = (NONE | BIT | VEC | <n>)

You can specify the value of LOCLMASK using the following:

NONE: Do not exclude any pixels from point collection.
BIT: Exclude only image pixels covered by the bitmap from point collection.
That is, use BIT when there are bitmap segments in one or more of the source-image files that define an exclusion region. When one of the source images contains multiple bitmaps, the last one is used.
VEC: Exclude all image pixels enclosed by polygons from point collection.
That is, use VEC when there are vector segments in one or more of the source-image files that define an exclusion region. When one of the source images contains multiple vector segments, the last one is used. The vector segment must be a polygon.
<n>: The specific segment number that contains the mask to use.

This parameter is optional.

MEMSIZE

The amount, in megabytes (MB), of internal memory to allocate to processing.

If sufficient memory is available, tiles can be processed in parallel for faster performance. In general, each tile being processed in parallel requires approximately 256 MB of memory. The values you specify may be overridden depending the amount of free memory available on the system.

Return Value

Returns: Program execution status

Type: PCI_INT

The return value is 0.

This function returns only if it executes successfully; otherwise, it throws an exception.

Details

FBMEXTRACT performs key-point and feature-descriptor extraction on image files for use in feature-based matching. A feature database (FDB) file is created for the input image, which contains a list of key points (image locations) with the associated feature descriptors of each key point. You can then use the FDB files as input with the FBMTIE algorithm to match key points to their corresponding key points in other images. The feature descriptor characterizes the appearance around each key point. Each key point is matched to the key points in other images with the closest feature descriptors.

Example

In the following example, a feature database (FDB) file is generated for an input image, using channel 1 and overview level 1.

from pci.fbmextract import fbmextract

fili = u"S129.PIX" # Input image
fdbdir = u""       # Save feature database to same folder as image
dbic = [1]         # Input channel 1
olevels = [1]      # Use full resolution (no downsample, overview level 1)
keypts = []        # Default maximum number of key points
dbiw = []          # No DBIW
loclmask = u""     # No exclusion mask
memsize = [2048]   # Use a maximum of 2048 MB of memory

fbmextract(fili, fdbdir, dbic, olevels, keypts, dbiw, loclmask, memsize)

Environments	PYTHON :: EASI
Quick links	Description :: Parameters :: Parameter descriptions :: Return Value :: Details :: Example :: Related