Next: Abstract

NDF
Routines for Accessing the
Extensible N-Dimensional Data Format
Version 1.12
Programmer's Manual

Starlink User Note 33.10
R.F. Warren-Smith & D.S. Berry
16th July 2012

CCLRC / Rutherford Appleton Laboratory
Particle Physics & Astronomy Research Council

Starlink Project

Retrieve hardcopy

Abstract
INTRODUCTION
- What is an NDF?
- The NDF Philosophy and Extensibility
- The Relationship with HDS
- Background Reading
- Scope of the Current Implementation
OVERVIEW
- Overview of an NDF
- Overview of the NDF_ Routines
- Error Handling
- Overview of a Typical Application
OBTAINING AND USING NDF IDENTIFIERS
- Accessing NDFs for Input
- NDF Identifiers
- Annulling Identifiers
- NDF Contexts: BEGIN and END
- Cloning Identifiers
NDF SHAPE AND SIZE INFORMATION
- Dimensionality and Bounds
- Dimension Sizes
- NDF Size
- ``Safe'' Dimension Sizes under Error Conditions
GENERAL PROPERTIES OF NDF COMPONENTS
- Specifying Component Names
- Component State
- Factors Determining a Component's State
- Restrictions on the Data Component's State
ACCESSING CHARACTER COMPONENTS
- Reading and Displaying Character Values
- Writing Character Values
- Character Component Length
- Resetting Character Components
ARRAY COMPONENT TYPES
- Numeric Types
- Complex Values
- Full Type Specifications
- Setting Component Types
ACCESSING ARRAY COMPONENTS
- Overview of Mapped Access to Array Components
- Mapping and Unmapping
- Implicit Unmapping
- Writing and Modifying Array Component Values
- More About Mapping Modes
- Initialisation Options
- Implicit Type Conversion
- Accessing Complex Values
- Mapping the Variance Component as Standard Deviations
- Restrictions on Mapped Access
BAD PIXELS
- The Need for Bad Pixels
- Recognition and Processing of Bad Pixels
- The Bad-Pixel Flag
- Obtaining and Using the Bad-Pixel Flag
- Requesting Explicit Checks for Bad Pixels
- Setting the Bad-Pixel Flag
- Interaction with Mapping and Unmapping
- Interaction with Initialisation Options
- A Practical Template for Handling the Bad-Pixel Flag
THE QUALITY COMPONENT IN MORE DETAIL
- Purpose of the Quality Component
- Accessing the Quality Array Directly
- The Bad-bits Mask
- Why Ignoring the Quality Component Works
- Controlling Automatic Quality Masking
EXTENSIONS
- Extensibility
- Extension Names and Software Packages
- The Contents of Extensions
- Accessing Existing Extensions
- Creating New Extensions
- Accessing Array Information in Extensions
- Deleting Extensions
- Enumerating an NDF's Extensions
ARRAY COMPONENT STORAGE FORM AND COMPRESSION
- General
- Obtaining the Storage Form
- Simple Storage Form
- Scaled Storage Form
- Delta compressed Storage Form
- Primitive Storage Form
  - Warning - possible pitfall:
ACCESSING NDFS FOR OUTPUT
- Using Existing NDFs
- Creating New NDFs via Parameters
- Conditional NDF Creation
- Creating Primitive NDFs
COMPONENT PROPAGATION
- General
- Propagation Rules for Standard NDF Components
- Propagation Rules for Extensions
- Creating New NDFs by Propagation
- Default Propagation of Components and Extensions
- Forcing Component Propagation
- Inhibiting Component Propagation
- Controlling Propagation of Extensions
NDF SECTIONS
- The Need for NDF Sections
- Creating NDF Sections
- The Distinction between Base NDFs and Sections
- Referring to Subsets and Super-sets
- The Transfer Window
- Changing Dimensionality
- Restrictions on the Use of Sections
- Restrictions on Mapped Access to Sections
- More Advanced Use: Partitioning
- Chunking
- Blocking
USING SUBSCRIPTS TO ACCESS NDF SECTIONS
- Specifying Lower and Upper Bounds
- Specifying Centre and Extent
- Using WCS Coordinates to Specify Sections
- Using Normalised Pixel Coordinates to Specify Sections
- Changing Dimensionality
- Mixing Bounds Expressions
MERGING AND MATCHING NDF ATTRIBUTES
- The Problem
- Merging and Matching Bad-Pixel Flags
- Matching NDF Bounds
- Merging and Matching Numeric Types
THE AXIS COORDINATE SYSTEM
- Pixel Coordinates
- Axis Coordinates
- Axis Arrays
- Pixel Positions and Dimensions
- Default Axis Array Values
- Contiguous and Non-Contiguous Pixels
- Processing Axis Array Values
- Axis Normalisation
AXIS COMPONENTS
- Overview of an NDF's Axis Components
- Axis Component States
- Restrictions on Axis Component States
- Defining a Default Axis Coordinate System
- Resetting Axis Components
- Accessing Axis Character Components
- Mapping Axis Arrays for Reading
- Unmapping Axis Arrays
- Writing and Modifying Axis Arrays
- Accessing Axis Variance Values as Standard Deviations
- Axis Normalisation Flags
- The Numeric Type of Axis Arrays
- The Storage Form of Axis Arrays
- Accessing Axis Components via NDF Sections
- Axis Extrapolation
CONNECTING WITH THE DATA SYSTEM
- NDF Names
- Finding and Importing NDFs
- A Note on Modes of Access
- Obtaining an HDS Locator for an NDF
- NDF Placeholders
- Creating NDFs via Placeholders
- Temporary NDFs
- Copying NDFs
- Selective Copying of NDF Components
- General Access to NDFs
- Deleting NDFs
ALTERING BOUNDS AND PIXEL INDICES
- Setting New Pixel-Index Bounds and Dimensionality
- Applying Pixel-Index Shifts
THE HISTORY COMPONENT
- Purpose of the History Component
- The History Component's State
- Preparing to Record History Information
- Resetting the History Component
- Default History Recording
- Propagation of History Information
- Explicitly Controlling History Text
- The History Update Mode
- Using Message Tokens in History Text
- History Text Width
- Formatting Options for History Text
- Automatic Error Recording
- Enquiring about Past History Information
- Accessing History by Date and Time
- Accessing Past History Text
- Modifying Past History
- Naming an Application
- Ending an Application
MISCELLANEOUS FACILITIES
- Restricting Access via NDF Identifiers
- Message System Routines
- Tuning the NDF_ System
COMPILING AND LINKING
- Standalone Applications
- ADAM Applications
EXAMPLE APPLICATIONS
- SHOW -- Display the size of an NDF
- SETTITLE -- Assign a New NDF Title
- GETMAX -- Obtain the Maximum Pixel Value
- GETSUM -- Sum the Pixel Values
- READIMG -- Read an image into an NDF
- ZAPPIX -- ``Zap'' Prominent Pixels in an Image
- ADD -- Add Two NDF Data Structures
- NDFTRACE -- Trace an NDF Structure
CLASSIFIED LIST OF FORTRAN ROUTINES
- Access to Existing NDFs
- Enquiring NDF Attributes
- Enquiring Component Attributes
- Creating and Deleting NDFs
- Setting NDF Attributes
- Setting Component Attributes
- Access to Component Values
- Enquiring and Setting Axis Attributes
- Access to Axis Values
- Access to World Coordinate System Information
- Creation and Control of Identifiers
- Handling NDF (and Array) Sections
- Matching and Merging Attributes
- Parameter System Routines
- Message System Routines
- Creating Placeholders
- Copying NDFs
- Handling Extensions
- Handling History Information
- Tuning the NDF_ system
- Compression
FORTRAN ROUTINE DESCRIPTIONS
- NDF_ACGET - Obtain the value of an NDF axis character component
- NDF_ACLEN - Determine the length of an NDF axis character component
- NDF_ACMSG - Assign the value of an NDF axis character component to a message token
- NDF_ACPUT - Assign a value to an NDF axis character component
- NDF_ACRE - Ensure that an axis coordinate system exists for an NDF
- NDF_AFORM - Obtain the storage form of an NDF axis array
- NDF_AMAP - Obtain mapped access to an NDF axis array
- NDF_ANNUL - Annul an NDF identifier
- NDF_ANORM - Obtain the logical value of an NDF axis normalisation flag
- NDF_AREST - Reset an NDF axis component to an undefined state
- NDF_ASNRM - Set a new logical value for an NDF axis normalisation flag
- NDF_ASSOC - Associate an existing NDF with an ADAM parameter
- NDF_ASTAT - Determine the state of an NDF axis component (defined or undefined)
- NDF_ASTYP - Set a new numeric type for an NDF axis array
- NDF_ATYPE - Obtain the numeric type of an NDF axis array
- NDF_AUNMP - Unmap an NDF axis array
- NDF_BAD - Determine if an NDF array component may contain bad pixels
- NDF_BASE - Obtain an identifier for a base NDF
- NDF_BB - Obtain the bad-bits mask value for the quality component of an NDF
- NDF_BEGIN - Begin a new NDF context
- NDF_BLOCK - Obtain an NDF section containing a block of adjacent pixels
- NDF_BOUND - Enquire the pixel-index bounds of an NDF
- NDF_CANCL - Cancel the association of an NDF with an ADAM parameter
- NDF_CGET - Obtain the value of an NDF character component
- NDF_CHUNK - Obtain an NDF section containing a chunk of contiguous pixels
- NDF_CINP - Obtain an NDF character component value via the ADAM parameter system
- NDF_CLEN - Determine the length of an NDF character component
- NDF_CLONE - Clone an NDF identifier
- NDF_CMPLX - Determine whether an NDF array component holds complex values
- NDF_CMSG - Assign the value of an NDF character component to a message token
- NDF_COPY - Copy an NDF to a new location
- NDF_CPUT - Assign a value to an NDF character component
- NDF_CREAT - Create a new simple NDF via the ADAM parameter system
- NDF_CREP - Create a new primitive NDF via the ADAM parameter system
- NDF_CREPL - Create a new NDF placeholder via the ADAM parameter system
- NDF_DELET - Delete an NDF
- NDF_DIM - Enquire the dimension sizes of an NDF
- NDF_END - End the current NDF context
- NDF_EXIST - See if an existing NDF is associated with an ADAM parameter
- NDF_FIND - Find an NDF and import it into the NDF_ system
- NDF_FORM - Obtain the storage form of an NDF array component
- NDF_FTYPE - Obtain the full type of an NDF array component
- NDF_GTDLT - Get compression details for a DELTA compressed NDF array component
- NDF_GTSZx - Get the scale and zero values for an NDF array component
- NDF_GTUNE - Obtain the value of an NDF_ system tuning parameter
- NDF_GTWCS - Obtain world coordinate system information from an NDF
- NDF_HAPPN - Declare a new application name for NDF history recording
- NDF_HCRE - Ensure that a history component exists for an NDF
- NDF_HDEF - Write default history information to an NDF
- NDF_HECHO - Write out lines of history text
- NDF_HEND - End NDF history recording for the current application
- NDF_HFIND - Find an NDF history record by date and time
- NDF_HGMOD - Get the history update mode for an NDF
- NDF_HINFO - Obtain information about an NDF's history component
- NDF_HNREC - Determine the number of NDF history records present
- NDF_HOUT - Display text from an NDF history record
- NDF_HPURG - Delete a range of records from an NDF history component
- NDF_HPUT - Write history information to an NDF
- NDF_HSDAT - Set the history date for an NDF
- NDF_HSMOD - Set the history update mode for an NDF
- NDF_ISACC - Determine whether a specified type of NDF access is available
- NDF_ISBAS - Enquire if an NDF is a base NDF
- NDF_ISIN - See if one NDF is contained within another NDF
- NDF_ISTMP - Enquire if an NDF is temporary
- NDF_LOC - Obtain an HDS locator for an NDF
- NDF_MAP - Obtain mapped access to an array component of an NDF
- NDF_MAPQL - Map the quality component of an NDF as an array of logical values
- NDF_MAPZ - Obtain complex mapped access to an array component of an NDF
- NDF_MBAD - Merge the bad-pixel flags of the array components of a pair of NDFs
- NDF_MBADN - Merge the bad-pixel flags of the array components of a number of NDFs
- NDF_MBND - Match the pixel-index bounds of a pair of NDFs
- NDF_MBNDN - Match the pixel-index bounds of a number of NDFs
- NDF_MSG - Assign the name of an NDF to a message token
- NDF_MTYPE - Match the types of the array components of a pair of NDFs
- NDF_MTYPN - Match the types of the array components of a number of NDFs
- NDF_NBLOC - Determine the number of blocks of adjacent pixels in an NDF
- NDF_NCHNK - Determine the number of chunks of contiguous pixels in an NDF
- NDF_NEW - Create a new simple NDF
- NDF_NEWP - Create a new primitive NDF
- NDF_NOACC - Disable a specified type of access to an NDF
- NDF_OPEN - Open an existing or new NDF
- NDF_PLACE - Obtain an NDF placeholder
- NDF_PROP - Propagate NDF information to create a new NDF via the ADAM parameter system
- NDF_PTSZx - Set new scale and zero values for an NDF array component
- NDF_PTWCS - Store world coordinate system information in an NDF
- NDF_QMASK - Combine an NDF quality value with a bad-bits mask to give a logical result
- NDF_QMF - Obtain the logical value of an NDF's quality masking flag
- NDF_RESET - Reset an NDF component to an undefined state
- NDF_SAME - Enquire if two NDFs are part of the same base NDF
- NDF_SBAD - Set the bad-pixel flag for an NDF array component
- NDF_SBB - Set a bad-bits mask value for the quality component of an NDF
- NDF_SBND - Set new pixel-index bounds for an NDF
- NDF_SCOPY - Selectively copy NDF components to a new location
- NDF_SCTYP - Obtain the numeric type of a scaled NDF array component
- NDF_SECT - Create an NDF section
- NDF_SHIFT - Apply pixel-index shifts to an NDF
- NDF_SIZE - Determine the size of an NDF
- NDF_SQMF - Set a new logical value for an NDF's quality masking flag
- NDF_SSARY - Create an array section, using an NDF section as a template
- NDF_STATE - Determine the state of an NDF component (defined or undefined)
- NDF_STYPE - Set a new type for an NDF array component
- NDF_TEMP - Obtain a placeholder for a temporary NDF
- NDF_TUNE - Set an NDF_ system tuning parameter
- NDF_TYPE - Obtain the numeric type of an NDF array component
- NDF_UNMAP - Unmap an NDF or a mapped NDF array
- NDF_VALID - Determine whether an NDF identifier is valid
- NDF_XDEL - Delete a specified NDF extension
- NDF_XIARY - Obtain access to an array stored in an NDF extension
- NDF_XGT0x - Read a scalar value from a component within a named NDF extension
- NDF_XLOC - Obtain access to a named NDF extension via an HDS locator
- NDF_XNAME - Obtain the name of the N'th extension in an NDF
- NDF_XNEW - Create a new extension in an NDF
- NDF_XNUMB - Determine the number of extensions in an NDF
- NDF_XPT0x - Write a scalar value to a component within a named NDF extension
- NDF_XSTAT - Determine if a named NDF extension exists
- NDF_ZDELT - Create a compressed copy of an NDF using DELTA compression
- NDF_ZSCAL - Create a compressed copy of an NDF using SCALE compression
THE NDF_ LIBRARY C INTERFACE
- Conventions Used in the C Interface
- Using the C Interface - a Few Peculiarities
- Building C Applications
ALPHABETICAL LIST OF C FUNCTIONS
OBSOLETE ROUTINES
- NDF_IMPRT - Import an NDF into the NDF_ system from HDS
- NDF_TRACE - Set the internal NDF_ system error-tracing flag
CHANGES AND NEW FEATURES
- Changes Introduced in V1.3
- Changes Introduced in V1.4
- Changes Introduced in V1.5
- Changes Introduced in V1.6
- Changes Introduced in V1.7
- Changes Introduced in V1.8
- Changes Introduced in V1.9
- Changes Introduced in V1.10
- Changes Introduced in V1.11
- Changes Introduced in V1.12
About this document ...

Next: Abstract

NDF Routines for Accessing the Extensible N-Dimensional Data Format Version 1.12 Programmer's Manual

CCLRC / Rutherford Appleton Laboratory Particle Physics & Astronomy Research Council

Starlink Project

Contents

NDF
Routines for Accessing the
Extensible N-Dimensional Data Format
Version 1.12
Programmer's Manual

CCLRC / Rutherford Appleton Laboratory
Particle Physics & Astronomy Research Council