This topic describes how to access various levels of NITF metadata in the ENVI API.

NITF metadata are stored in a top-level dictionary that contains the following collections of NITF segments:

• Header
• Image
• Annotation
• Text
• Data extension segment (DES)

Refer to the UML diagram that shows the hierarchy of dictionaries and lists that comprise the metadata collection. Use a dot syntax notation to access different levels of metadata. Click on the above hyperlinks for code examples that show how to retrieve metadata values for different NITF segments. Key names are not case-sensitive.

Here are some general tips for retrieving metadata from a NITF raster.

• Use the HasKey method to determine if a node is present, for example:

check = metadata.Image[0].HasKey('TRE')

• Use the JSON_SERIALIZE function to serialize the contents of the top-level dictionary into a JSON string, for example:

jsonStr = JSON_SERIALIZE(metadata)

• Use the N_ELEMENTS function to determine the number of items in a list. The following example returns the number of items in a list of TREs within a header segment:

numItems = N_ELEMENTS(metadata.Header.TRE[0].Item)

• Use an implied PRINT command to print the entire collection. The ordering of tags may appear scrambled because IDL dictionaries do not preserve the ordering of tags (to improve performance):

PRINT, metadata, /IMPLIED_PRINT

Header Segment Examples

---

The ENVINITFMetadata function returns header metadata when you set the ALL or HEADER keyword. Here are some examples of working with the header dictionary.

1. Start the application in headless mode.

IDL> e = ENVI(/HEADLESS)

2. Select a NITF raster from the example data in the ENVI installation path.

ENVI> file = FILEPATH('MultiSegmentExample.ntf', $
  ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])

3. Get the header metadata.

ENVI> metadata = ENVINITFMetadata(raster, /HEADER)

4. Check if a Header key exists.

ENVI> check = metadata.HasKey('Header')

ENVI> Print, check

    1            

5. Get the value of the FILE_NAME key.

ENVI> fileName = metadata.Header.FILE_NAME

ENVI> Print, fileName

    location\MultiSegmentExample.ntf            

6. Get the header security value.

ENVI> securityClass = metadata.Header.Security.SCLAS

ENVI> Print, securityClass

    U            

7. Check if a TRE key exists.

ENVI> checkTRE = metadata.Header.HasKey('TRE')

ENVI> Print, checkTRE

    1            

8. Get the number of TREs.

ENVI> numTREs = N_ELEMENTS(metadata.Header.TRE)

ENVI> Print, numTREs

    1            

9. Get the name of the TRE.

ENVI> name = metadata.Header.TRE[0].Name

ENVI> Print, name

    PIAPRC            

10. Get the number of items in the TRE.

ENVI> numItems = N_ELEMENTS(metadata.Header.TRE[0].Item)

ENVI> Print, numItems

    31            

11. Get the value of the fourth item of the TRE.

ENVI> value = metadata.Header.TRE[0].Item[3].VALUE

ENVI> Print, value

    FM Control Number            

Header UML Diagram

Image Segment Examples

---

The ENVINITFMetadata function returns image segment metadata for the NITF rasters that you pass to it. Here are some examples of working with the image dictionary:

1. Start the application in headless mode.

IDL> e = ENVI(/HEADLESS)

2. Select a NITF raster from the example data in the ENVI installation path.

ENVI> file = FILEPATH('MultiSegmentExample.ntf', $
  ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])

3. Get all metadata.

ENVI> metadata = ENVINITFMetadata(raster)

4. Check if an Image key exists.

ENVI> check = metadata.HasKey('Image')

ENVI> Print, check

    1            

5. Get the number of image segments.

ENVI> numImages = N_ELEMENTS(metadata.Image)

ENVI> Print, numImages

    5            

6. Get the number of bands in the second image segment.

ENVI> numBands = metadata.Image[1].NBANDS

ENVI> Print, numBands

    1            

7. Get the image security value of the second image segment.

ENVI> securityClass = metadata.Image[1].Security.SCLAS

ENVI> Print, securityClass

    U            

8. Check if a Band key exists in the second image segment.

ENVI> checkBand = metadata.Image[1].HasKey('Band')

ENVI> Print, checkBand

    1            

9. Get the IREP value of the band in the second image segment.

irepBand = metadata.Image[1].Band[0].IREPBAND

    M            

10. This example file does not have any lookup tables (LUTs), but the following code shows how to get the details of an LUT for a specific band within an image segment:

IF (metadata.Image[1].Band[0].HasKey('DATA_LUT')) THEN BEGIN

  dataLUT = metadata.Image[1].Band[0].DATA_LUT

  Print, N_ELEMENTS(metadata.Image[1].Band[0].DATA_LUT)

ENDIF

Image UML Diagram

Annotation Segment Examples

---

The ENVINITFMetadata function returns annotation metadata when you set the ALL keyword. Here are some examples of working with the annotation dictionary:

1. Start the application in headless mode.

IDL> e = ENVI(/HEADLESS)

2. Select a NITF raster from the example data in the ENVI installation path.

ENVI> file = FILEPATH('MultiSegmentExample.ntf', $
  ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])

3. Get all metadata.

ENVI> metadata = ENVINITFMetadata(raster, /ALL)

4. Check if an Annotation key exists.

ENVI> check = metadata.HasKey('Annotation')

ENVI> Print, check

    1            

5. Get the number of annotation segments.

ENVI> numAnno = N_ELEMENTS(metadata.Annotation)

ENVI> Print, numAnno

    4            

6. Get the ANNO_TYPE key of the first annotation segment.

ENVI> Print, metadata.Annotation[0].ANNO_TYPE

    C            

7. This example file does not have any CGM data, but the following code shows how to get the details of CGM data within an annotation segment:

IF (metadata.Annotation[0].HasKey('DATA_CGMDATA')) THEN BEGIN

  dataCGM = metadata.Annotation[0].DATA_CGMDATA

  Print, dataCGM[0:3]

ENDIF

8. Check if the first annotation segment has any TREs.

ENVI> checkTRE = metadata.Annotation[0].HasKey('TRE')

ENVI> Print, checkTRE

    1            

ENVI> numTREs = N_ELEMENTS(metadata.Annotation[0].TRE)

ENVI> Print, numTREs

    2            

9. Check the number of items in the second TRE in the first annotation segment.

ENVI> numItems = N_ELEMENTS(metadata.Annotation[0].TRE[1])

ENVI> Print, numItems

    6            

10. Get the name of the second TRE within the first annotation segment.

ENVI> Print, metadata.Annotation[0].TRE[1].NAME

    PIAEQA            

11. Get the value of the fifth item in the second TRE in the first annotation segment.

ENVI> Print, metadata.Annotation[0].TRE[1].Item[4].VALUE

    Equipment Manufacturer            

12. Check if an Object key exists in the first annotation segment.

ENVI> checkObject = metadata.Annotation[0].HasKey('Object')

ENVI> Print, checkObject

    1            

13. Get the number of Object keys in the first annotation segment.

ENVI> numObjects = N_ELEMENTS(metadata.Annotation[0].Object)

ENVI> Print, numObjects

    1            

14. This example file does not have any DATA_BMP keys, but the following code shows how to get the details of the DATA_BMP key within an annotation segment:

IF (metadata.Annotation[0].Object[0].HasKey('DATA_BMP')) THEN BEGIN

  dataBMP = metadata.Annotation[0].Object[0].DATA_BMP

  Print, N_ELEMENTS(dataBMP)

ENDIF

Annotation UML Diagram

Text Segment Examples

---

The ENVINITFMetadata function returns text metadata when you set the ALL keyword. Here are some examples of working with the text dictionary.

1. Start the application in headless mode.

IDL> e = ENVI(/HEADLESS)

2. Select a NITF raster from the example data in the ENVI installation path.

ENVI> file = FILEPATH('MultiSegmentExample.ntf', $
  ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])

3. Get all metadata.

ENVI> metadata = ENVINITFMetadata(raster, /ALL)

4. Check if a Text key exists.

ENVI> check = metadata.HasKey('Text')

ENVI> Print, check

    1            

5. Get the number of text segments.

ENVI> numText = N_ELEMENTS(metadata.Text)

ENVI> Print, numText

    1            

6. Get the header ID of the text segment.

ENVI> Print, metadata.Text[0].TEXTID

    0000001            

7. Get the text security value.

ENVI> Print, metadata.Text[0].Security.SCLAS

    U            

8. Check if a TRE key exists in the text segment.

ENVI> checkTRE = metadata.Text[0].HasKey('TRE')

ENVI> Print, checkTRE

    1            

9. Get the number of TREs in the text segment.

ENVI> numTREs = N_ELEMENTS(metadata.Text[0].TRE)

ENVI> Print, numTREs

    3            

10. Get the number of items in the second TRE.

ENVI> numItems = N_ELEMENTS(metadata.Text[0].TRE[1].Item)

ENVI> Print, numItems

    7            

11. Get the name of the second TRE in the text segment.

ENVI> Print, metadata.Text[0].TRE[1].NAME

    PIAPEA            

12. Get the value of the fourth item of the second TRE in the text segment.

ENVI> Print, metadata.Text[0].TRE[1].Item[3].VALUE

    First Name            

Text UML Diagram

Data Extension Segment (DES) Examples

---

The ENVINITFMetadata function returns DES metadata when you set the ALL keyword. Here are some examples of working with the DES dictionary:

1. Start the application in headless mode.

IDL> e = ENVI(/HEADLESS)

2. Select a NITF raster from the example data in the ENVI installation path. This particular file has a DES, whereas the other example used in this topic does not.

ENVI> file = FILEPATH('DESExample.ntf', $
  ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])

3. Get all metadata.

ENVI> metadata = ENVINITFMetadata(raster, /ALL)

4. Check if a DES key exists.

ENVI> check = metadata.HasKey('DES')

ENVI> Print, check

    1            

5. Get the number of DESes.

ENVI> numDES = N_ELEMENTS(metadata.DES)

ENVI> Print, numDES

    1            

6. Check if a DES header exists.

ENVI> checkDESHdr = metadata.DES[0].HasKey('DESHeader')

ENVI> Print, checkDESHdr

    1            

7. Get the number of elements in the DES header.

ENVI> numDESHdrs = N_ELEMENTS(metadata.DES[0].DESHeader)

ENVI> Print, numDESHdrs

    1            

8. Get the NAME key of the DES header.

ENVI> Print, metadata.DES[0].DESHeader[0].NAME

    UserDefinedSubheaders            

9. Get the number of items in the DES header.

ENVI> numDesItems = N_ELEMENTS(metadata.DES[0].DESHeader[0].Item)

ENVI> Print, numDESItems

    1            

10. Get the VALUE key of the DES header item.

ENVI> Print, metadata.DES[0].DESHeader[0].Item[0].VALUE

    User-Defined Subheaders            

11. Get the DESC key of the DES header item.

ENVI> Print, metadata.DES[0].DESHeader[0].Item[0].DESC

    ICAw            

12. Get the DES security value.

ENVI> Print, metadata.DES[0].Security.SCLAS

    U            

13. This example file does not have any DATA_DES keys, but the following code shows how to get the details of the DATA_DES key within an annotation segment.

Print, metadata.DES[0].DESID

IF (metadata.DES[0].HasKey('DATA_DES')) THEN BEGIN

  dataDES = metadata.DES[0].DATA_DES

  Print, N_ELEMENTS(dataDES)

ENDIF

Data Extension Segment UML Diagram

 

Key Names

---

This section lists the valid NITF keys for each metadata node. Refer to the Reference Library for NITFS Users web site for specification documents that define these keys.

Note: Asterisks indicate that you should use .HasKey('DATA_CGM') to determine if that key is present.

Header Keys

NAME

FILE_NAME

VERSION

CLEVEL

STYPE

OSTAID

FDT

FTITLE

ENCRYP

FSCOP

FSCPYS

FBKGC

ONAME

OPHONE

FL

HL

Image Keys

NAME

IMGUID

OFFSET

LISH

LI

IID1

IDATIM

TGTID

IID2

ITITLE

ENCRYP

ISORCE

NROWS

NCOLS

PVTYPE

IREP

ICAT

ABPP

PJUST

ICORDS

IGEOLO

ZONE

CORNERS

CELLSIZE

NICOM

ICOM

IC

COMRAT

J2K_R_LEVELS

J2K_Q_LAYERS

NBANDS

ISYNC

IMODE

NBPR

NBPC

NPPBH

NPPBV

NBPP

DLVL

ALVL

LOC

IMAG

HAS_MASK

MASK_VALUE

SUBRECT

SPATIAL_SUBSET

IS_JP2

Image Band Keys

NAME

IREPBAND

ISUBCAT

ITYPE

IFC

IMFLT

NLUTS

DATA_LUT *

Annotation (Graphics) Keys

NAME

FILE_PART_TYPE

ANNO_ID

ANNO_NAME

ENCRYP

ANNO_TYPE

DLVL

ALVL

LOC

LOC_CCS

SIZE

SBND_OFFSET

SCOLOR

SRES2

NLIPS

NPIXPL

NWDTH

SNBPP

SLOC2

SNUM

SROT

SNELUT

CGM_DATALENGTH

DATA_CGMDATA *

Annotation (Graphics) Object Keys

NAME

TYPE

TEXT_STRING

TEXT_HEIGHT

TEXT_FONT

TEXT_COLOR

TEXT_BG_COLOR

LINE_COLOR

LINE_STYLE

LINE_WIDTH

ARROW_HEAD_ANGLE

ARROW_HEAD_LENGTH

FILL_COLOR

FILL_STYLE

EDGE_VISIBILITY

ELLIPSE_CENTER

ELLIPSE_RAD1

ELLIPSE_RAD2

ELLIPSE_START

ELLIPSE_END

ELLIPSE_CLOSE_TYPE

ORIEN

NPOINTS

BITS_PER_PIXEL

NELUT

DATA_XPTS *

DATA_YPTS *

DATA_EDGE_OUT_FLAGS *

DATA_LUT *

DATA_BITMAP *

Text Keys

NAME

TXTUID

TEXTID

TXTALVL

TXTDT

TXTTL

ENCRYP

TXTFMT

TEXT

Security Keys

NAME

SCLAS

SCLSY

SCODE

SCTLH

SREL

SDCTP

SDCDT

SDCXM

SDG0

SDGDT

SCLTX

SCATP

SCAUT

SCRSN

SSRDT

SCTLN

SDWNG

SDEVT

TRE Keys

NAME

TAGUID

TAG_NAME

IS_OVERFLOW

IS_RAW_DATA

TRE Item Keys

NAME

VALUE

DESC

SIZE

TYPE

DES Keys

NAME

DESID

DESVER

DESOFLW

DESITEM

DATASIZE

IS_UNKNOWN_DES

DATA_DES *

DES Header Keys

NAME

DES Header Item Keys

NAME

VALUE

DESC

SIZE

TYPE