NCL Website header
NCL Home > Documentation > Functions > Array manipulators


Unpacks bit fields from an array.

Available in version 6.5.0 and later.


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

	return_val  :  typeof(packedvar)



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


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.


The length of the bit-field.

Return value

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


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.

See Also



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:

   dimq = dimsizes(250m_16_days_VI_Quality)
   lwFlag_1d = dim_gbits(ndtooned(250m_16_days_VI_Quality), 2, 3, 13, dimq)
   lwFlag = onedtond(lwFlag_1d, dimq)