acefilter: filter catalogs and object masks

Package: ace

Synopsis

Usage

acefilter images

Parameters

images

List of images with catalogs or object masks to be filtered. The images may be single images or multi-extension format (MEF) files.

icatalogs = "!catalog"

Input list of catalogs to be filtered. The list must match the list of input images. Keyword pointers and substitution patterns may be used in addtion to any other IRAF list format. The catalog need not have been produced by ACE and may be any format supported by the tables package. However, if a filtered object mask is to be produced the catalog must contain a field, specified by the catomid parameter, with the object mask identification numbers.

ocatalogs = "+new_cat"

Output list of filtered catalogs. The list must either be empty to select no catalog output or match the list of input images. Keyword pointers and substitution patterns may be used in addition to any other IRAF list format. Extensions will be supplied if needed. MEF input images and catalogs will produce MEF binary table catalogs with matching extension names.

objmasks = ""

Output list of filtered object masks. The list must either be empty to select no object mask output or match the list of input images. Keyword pointers and substitution patterns may be used in addition to any other IRAF list format. Extensions will be supplied if needed. MEF input images will produced MEF binary table mask files with matching extension names. To produce an output mask an input mask must exist and be specified by the "OBJMASK" keyword in the catalog header or the image header (in that order).

catfilter = ""

Catalog filter expression. If no expression is given then all input catalog records are selected. An expression must evaluate to a boolean value. Operands are case sensitive catalog field names. Field names are those defined by the tables package. In particular, simple text fields may be used as input catalogs and the field names are "c1", "c2", etc.

logfiles = "STDOUT"

List of output log files. The list may be empty. Output is appended to existing files. The special name "STDOUT" may be used for output to the standard output (terminal or redirection output).

extnames = ""

List of extension name patterns for MEF files. Note the patterns must match the entire name.

omtype = "all" (all|numbers|boolean|bnumbers|bboolean)

Type of output object mask numbers. All types use a value of zero for background pixels. In all masks except the boolean masks, values up to 10 are used for bad and flagged pixels and above 10 are used for objects. A "boolean" mask uses values of 1 for all non-background pixels. A "numbers" mask uses the detection number for each object. The "all" type adds bit flags to the detection number for boundary, grown, and split pixels. The "bnumbers" and "bboolean" only mark boundary pixels and set interior detection pixels to zero. Note that for later evaluations using the object segmentations the type must be "all".

catomid = "NUM"

Catalog field containing the object mask identification number for filtering object masks. This is only used when outputing a filtered object mask.

update = no

Write output catalog and object mask names to the image header under the keywords "CATALOG" and "OBJMASK"?

Description

This task filters catalogs and object masks by selecting records and object mask identification numbers for catalog records satisfying a filter expression. Input images and catalogs are required. The input image is used for extension names, keyword references, and object mask matching.

The input catalog is normally produced by an ace package but this task may be used with any catalog supported by the tables package. The only requirement on a catalog is that in order to filter object masks it must contain a field with the object mask identification numbers. Since the ace cataloging tasks allow renaming and fields created using functions and expressions, the user must use field names as they appear in the catalog. The task tlcol may be used to check the field names. The field names used in the filter expression and catalog object identification selection are case sensitive even though tables package tasks may not be.

The heart of this task is the filter expression specified by the catfilter expression. Normally an expression is specified though a null string, which selects all records, may be useful for some purposes. For general information on expressions see the help topic expressions. The operands in the expression are catalog field names. The functions provided for output catalog fields in ace may be used in filter expressions. The filter expresion, if one is given, must evaluate to a boolean value.

An output filtered object mask is produced when an output object mask file name is specified, possibly through a keyword reference, and an existing object mask is defined by the "OBJMASK" keyword in the input catalog or input image (in that order). A filtered object mask means a mask with only the object mask numbers, as given by the catalog field with name specified by the catomid parameter, for the catalog records matching the filter. Input object mask numbers for bad pixels and flagged pixels with values up to 10 are also included in the output object mask.

An output mask type is specified by the omtype parameter. The typ allows using this task might to convert an object mask to a different with or without filtering.

The update parameter is provided to allow filtering catalogs and object masks without resetting the image header keywords used by default in other tasks; e.g. acedisplay.

Examples

Revisions

See also

acecatalog, acetvmark, tables, expressions