NCL Home > Documentation > Functions > Array manipulators

get_bitfield

Unpacks bit fields from an array.

Available in version 6.5.0 and later.

Prototype

	function get_bitfield (
		packedvar  : numeric,  ; byte, ubyte, short, ushort, integer
		startbit   : integer,  
		numbits    : integer   
	)

	return_val  :  typeof(packedvar)

Arguments

packedvar

The array of any dimensionality to be unpacked. It can be of type byte, ubyte, short, ushort, or integer.

startbit

The bit number of the start of the bit-field. Bits are numbered from right-to-left, or least-significant to most-significant, starting with zero, as per common convention. startbit should be the most signficant bit of the bit-field.

numbits

The length of the bit-field.

Return value

The return array will be the same type and shape as packedvar.

Description

Satellite data products, such as NASA's MODIS, often contain data packed as bitfields within a variable of integer type. By convention in these data products, the bits are numbered from right to left, or least-significant to most-significant, beginning with zero. get_bitfield is a convenience function for extracting such bit-fields. It is similar to (and implemented in terms of) dim_gbits, but is intended to be easier to use in this specific use-case.

Examples

Consider the following description of a packed variable, extracted from a MODIS file:

     ushort 250m_16_days_VI_Quality ( YDim_MODIS_Grid_16DAY_250m_500m_VI, XDim_MODIS_Grid_16DAY_250m_500m_VI )
         long_name :	250m 16 days VI Quality
         units :	bit field
         valid_range :	( 0, 65534 )
         _FillValue :	65535
         Legend :	
	 Bit Fields Description (Right to Left): 
	[0-1] : MODLAND_QA [2 bit range] 
		 00: VI produced, good quality 
		 01: VI produced, but check other QA 
		 10: Pixel produced, but most probably cloudy 
		 11: Pixel not produced due to other reasons than clouds 
	[2-5] : VI usefulness [4 bit range] 
		 0000: Highest quality 
		 0001: Lower quality  
		 0010..1010: Decreasing quality 
		 1100: Lowest quality 
		 1101: Quality so low that it is not useful 
		 1110: L1B data faulty 
		 1111: Not useful for any other reason/not processed 
	[6-7] : Aerosol quantity [2 bit range] 
		 00: Climatology 
		 01: Low 
		 10: Average 
		 11: High (11) 
	[8] : Adjacent cloud detected; [1 bit range] 
		 1: Yes 
		 0: No 
	[9] : Atmosphere BRDF correction performed [1 bit range] 
		 1: Yes 
		 0: No 
	[10] : Mixed clouds  [1 bit range] 
		 1: Yes 
		 0: No 
	[11-13] : Land/Water Flag [3 bit range] 
		 000: Shallow ocean 
		 001: Land (Nothing else but land) 
		 010: Ocean coastlines and lake shorelines 
		 011: Shallow inland water 
		 100: Ephemeral water 
		 101: Deep inland water 
		 110: Moderate or continental ocean 
		 111: Deep ocean 
	[14] : Possible snow/ice [1 bit range] 
		 1: Yes 
		 0: No 
	[15] : Possible shadow [1 bit range] 
		 1: Yes 
		 0: No
         hdf_name :	250m 16 days VI Quality

Nine channels of information are packed Within this unsigned-short 2D variable. To extract the "Land/Water Flag":

   lwFlag = get_bitfield(250m_16_days_VI_Quality, 13, 3)

Contrast this usage with the equivalent call to the more flexible and general dim_gbits: