Welcome to the Harris Geospatial documentation center. Here you will find reference guides and help documents.


  >  Docs Center  >  ENVI API  >  Data Control  >  NITF API Metadata Background

NITF API Metadata Background

NITF API Metadata Background

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:

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.
  2. IDL> e = ENVI(/HEADLESS)
  3. Select a NITF raster from the example data in the ENVI installation path.
  4. ENVI> file = FILEPATH('MultiSegmentExample.ntf', $
      ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])
  5. Get the header metadata.
  6. ENVI> metadata = ENVINITFMetadata(raster, /HEADER)
  7. Check if a Header key exists.
  8. ENVI> check = metadata.HasKey('Header')
    ENVI> Print, check
       
        1            
     
  9. Get the value of the FILE_NAME key.
  10. ENVI> fileName = metadata.Header.FILE_NAME
    ENVI> Print, fileName
       
        location\MultiSegmentExample.ntf            
     
  11. Get the header security value.
  12. ENVI> securityClass = metadata.Header.Security.SCLAS
    ENVI> Print, securityClass
       
        U            
     
  13. Check if a TRE key exists.
  14. ENVI> checkTRE = metadata.Header.HasKey('TRE')
    ENVI> Print, checkTRE
     
        1            
  15. Get the number of TREs.
  16.    
    ENVI> numTREs = N_ELEMENTS(metadata.Header.TRE)
    ENVI> Print, numTREs
     
        1            
  17. Get the name of the TRE.
  18.  
    ENVI> name = metadata.Header.TRE[0].Name
    ENVI> Print, name
     
        PIAPRC            
  19. Get the number of items in the TRE.
  20.  
    ENVI> numItems = N_ELEMENTS(metadata.Header.TRE[0].Item)
    ENVIPrint, numItems
     
        31            
         
  21. Get the value of the fourth item of the TRE.
  22. 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.
  2. IDL> e = ENVI(/HEADLESS)
  3. Select a NITF raster from the example data in the ENVI installation path.
  4. ENVI> file = FILEPATH('MultiSegmentExample.ntf', $
      ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])
  5. Get all metadata.
  6. ENVI> metadata = ENVINITFMetadata(raster)
  7. Check if an Image key exists.
  8. ENVI> check = metadata.HasKey('Image')
    ENVI> Print, check
       
        1            
     
  9. Get the number of image segments.
  10. ENVI> numImages = N_ELEMENTS(metadata.Image)
    ENVIPrint, numImages
     
        5            
     
  11. Get the number of bands in the second image segment.
  12. ENVI> numBands = metadata.Image[1].NBANDS
    ENVI> Print, numBands
       
        1            
     
  13. Get the image security value of the second image segment.
  14. ENVI> securityClass = metadata.Image[1].Security.SCLAS
    ENVI> Print, securityClass
       
        U            
     
  15. Check if a Band key exists in the second image segment.
  16. ENVI> checkBand = metadata.Image[1].HasKey('Band')
    ENVI> Print, checkBand
     
        1            
     
  17. Get the IREP value of the band in the second image segment.
  18. irepBand = metadata.Image[1].Band[0].IREPBAND
     
        M            
     
  19. 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:
  20. 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.
  2. IDL> e = ENVI(/HEADLESS)
  3. Select a NITF raster from the example data in the ENVI installation path.
  4. ENVI> file = FILEPATH('MultiSegmentExample.ntf', $
      ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])
  5. Get all metadata.
  6. ENVI> metadata = ENVINITFMetadata(raster, /ALL)
  7. Check if an Annotation key exists.
  8. ENVI> check = metadata.HasKey('Annotation')
    ENVI> Print, check
       
        1            
     
  9. Get the number of annotation segments.
  10. ENVI> numAnno = N_ELEMENTS(metadata.Annotation)
    ENVI> Print, numAnno
     
        4            
     
  11. Get the ANNO_TYPE key of the first annotation segment.
  12. ENVI> Print, metadata.Annotation[0].ANNO_TYPE
     
        C            
     
  13. 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:
  14. IF (metadata.Annotation[0].HasKey('DATA_CGMDATA')) THEN BEGIN
      dataCGM = metadata.Annotation[0].DATA_CGMDATA
      Print, dataCGM[0:3]
    ENDIF
  15. Check if the first annotation segment has any TREs.
  16. ENVI> checkTRE = metadata.Annotation[0].HasKey('TRE')
    ENVI> Print, checkTRE
         
        1            
     
    ENVI> numTREs = N_ELEMENTS(metadata.Annotation[0].TRE)
    ENVI> Print, numTREs
     
        2            
     
  17. Check the number of items in the second TRE in the first annotation segment.
  18. ENVI> numItems = N_ELEMENTS(metadata.Annotation[0].TRE[1])
    ENVIPrint, numItems
     
        6            
     
  19. Get the name of the second TRE within the first annotation segment.
  20. ENVI> Print, metadata.Annotation[0].TRE[1].NAME
         
        PIAEQA            
     
  21. Get the value of the fifth item in the second TRE in the first annotation segment.
  22. ENVI> Print, metadata.Annotation[0].TRE[1].Item[4].VALUE
         
        Equipment Manufacturer            
     
  23. Check if an Object key exists in the first annotation segment.
  24. ENVI> checkObject = metadata.Annotation[0].HasKey('Object')
    ENVI> Print, checkObject
     
        1            
         
  25. Get the number of Object keys in the first annotation segment.
  26. ENVI> numObjects = N_ELEMENTS(metadata.Annotation[0].Object)
    ENVI> Print, numObjects
     
        1            
     
  27. 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:
  28. 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.
  2. IDL> e = ENVI(/HEADLESS)
  3. Select a NITF raster from the example data in the ENVI installation path.
  4. ENVI> file = FILEPATH('MultiSegmentExample.ntf', $
      ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])
  5. Get all metadata.
  6. ENVI> metadata = ENVINITFMetadata(raster, /ALL)
  7. Check if a Text key exists.
  8. ENVI> check = metadata.HasKey('Text')
    ENVI> Print, check
     
        1            
     
  9. Get the number of text segments.
  10. ENVI> numText = N_ELEMENTS(metadata.Text)
    ENVI> Print, numText
     
        1            
     
  11. Get the header ID of the text segment.
  12. ENVI> Print, metadata.Text[0].TEXTID
     
        0000001            
     
  13. Get the text security value.
  14. ENVI> Print, metadata.Text[0].Security.SCLAS
     
        U            
     
  15. Check if a TRE key exists in the text segment.
  16. ENVI> checkTRE = metadata.Text[0].HasKey('TRE')
    ENVI> Print, checkTRE
     
        1            
     
  17. Get the number of TREs in the text segment.
  18. ENVI> numTREs = N_ELEMENTS(metadata.Text[0].TRE)
    ENVI> Print, numTREs
     
        3            
     
  19. Get the number of items in the second TRE.
  20. ENVI> numItems = N_ELEMENTS(metadata.Text[0].TRE[1].Item)
    ENVI> Print, numItems
     
        7            
     
  21. Get the name of the second TRE in the text segment.
  22. ENVI> Print, metadata.Text[0].TRE[1].NAME
     
        PIAPEA            
     
  23. Get the value of the fourth item of the second TRE in the text segment.
  24. 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.
  2. IDL> e = ENVI(/HEADLESS)
  3. 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.
  4. ENVI> file = FILEPATH('DESExample.ntf', $
      ROOT_DIR=e.ROOT_DIR, SUBDIR=['data','NITFExamples'])
  5. Get all metadata.
  6. ENVI> metadata = ENVINITFMetadata(raster, /ALL)
  7. Check if a DES key exists.
  8. ENVI> check = metadata.HasKey('DES')
    ENVI> Print, check
     
        1            
     
  9. Get the number of DESes.
  10. ENVI> numDES = N_ELEMENTS(metadata.DES)
    ENVI> Print, numDES
     
        1            
     
  11. Check if a DES header exists.
  12. ENVI> checkDESHdr = metadata.DES[0].HasKey('DESHeader')
    ENVI> Print, checkDESHdr
     
        1            
     
  13. Get the number of elements in the DES header.
  14. ENVI> numDESHdrs = N_ELEMENTS(metadata.DES[0].DESHeader)
    ENVI> Print, numDESHdrs
     
        1            
     
  15. Get the NAME key of the DES header.
  16. ENVI> Print, metadata.DES[0].DESHeader[0].NAME
     
        UserDefinedSubheaders            
     
  17. Get the number of items in the DES header.
  18. ENVI> numDesItems = N_ELEMENTS(metadata.DES[0].DESHeader[0].Item)
    ENVI> Print, numDESItems
     
        1            
     
  19. Get the VALUE key of the DES header item.
  20. ENVI> Print, metadata.DES[0].DESHeader[0].Item[0].VALUE
     
        User-Defined Subheaders            
     
  21. Get the DESC key of the DES header item.
  22. ENVI> Print, metadata.DES[0].DESHeader[0].Item[0].DESC
     
        ICAw            
     
  23. Get the DES security value.
  24. ENVI> Print, metadata.DES[0].Security.SCLAS
     
        U            
     
  25. 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.
  26. 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



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us