tsmApi: Tutorial


READING TILES FROM A DATASET

Once you have opened a dataset connection, you can then proceed to read tiles from that dataset. For this we can use the tsmAllocReadTile function which requires the tile (x,y) coordinates and the level number of the pyramid we wish to read the tile from. For the purposes of illustration, we shall pick the tile at coordinate (0,0) of level 2. (You can of course find the valid ranges of these values by using tsmGet to retrieve the dataset's tspec structure, as discussed in the earlier tutorial on Querying a Dataset Connection). 

   TsmConnection connect;
   uchar         *tileBuffer;

   connect = tsmConnect( name, "r", NULL );
   tsmAllocReadTile( connect, 0, 0, 2, &tileBuffer );
   /* Do some processing on the tile buffer */
   tsmFreeTileBuffer( tileBuffer );
   tsmDisconnect( connect );

Note that we pass this function a reference to a (uchar *) variable and tsmApi will automatically manage the allocation of any buffers and simply return you a valid buffer with the tile data in it. We can then use the tsmFreeTileBuffer function to signal that you have finished using the data. That buffer can then be freed, or more efficently, tsmApi can use this buffer for a subsequent tsmAllocReadTile call.

Using tsmAllocReadTile is fine for accessing single tiles, or for reading tiles from local disk. However, when accessing multiple tile data from a DPSS it is more efficient to build a request list of all the tiles we desire. We send that request list to the DPSS and it will in turn send us all of those tiles (although not in any predictable order). In order to build and send this request list, and then read each tile as it comes in, we use the following tsmApi constructs: 

   TsmTileHeader *tileHeader;
   uchar         *tileBuffer;

   tsmTileReqBegin( connect );
   tsmTileReqAdd( connect, 0, 0, 2, TSM_NOW );
   tsmTileReqEnd( connect );  /* sends the request list */

   tsmAllocReadNextTile( connect, &tileHeader, &tileBuffer );

   tsmFreeTile( tileBuffer, tileHeader );
Of course, the normal thing to do is to perform lots of tsmTileReqAdd and tsmAllocReadNextTile calls inside separate loops. Note also that although this request list approach was developed primarily for accessing data efficiently from a DPSS, it will work well for local disk tile access too. Note also that the tsmAllocReadNextTile call writes data to a tileHeader buffer as well as a tileBuffer. The tile header gives us all the information that we require about the raw data that has been put into the tile buffer. For example, it will tell us the tile size, coordinates, level, checksum, etc. for the tile. We have a number of routines available to help us allocate, free, and query the tile header structure, e.g. 
   TsmTileHeader *tileHeader;
   int           tx, ty, level;

   /* open the connection, allocate a tile buffer, and send a tile request */

   tileHeader = tsmAllocTileHeader();
   tsmAllocReadNextTile( connect, &tileHeader, &tileBuffer );

   tx    = tsmTileHeaderX( tileHeader );
   ty    = tsmTileHeaderY( tileHeader );
   level = tsmTileHeaderLevel( tileHeader );

   tsmFreeTileHeader( tileHeader );

   /* deallocate the tile buffer and disconnect from dataset */
Note that you can free the header and tile buffers individually using the tsmFreeTileHeader and tsmFreeTileBuffer calls, or you can free them both at once with the tsmFreeTile call.

Next Tutorial: Reading Tiles with Manual Buffer Allocation
Previous Tutorial: Querying a Dataset Connection
Manual Page References: tsmAllocReadTile, tsmAllocReadNextTile, tsmTileReqBegin, tsmTileReqAdd, tsmTileReqEnd, tsmFreeTile, TsmTileHeader

Back to The tsmApi Home Page / The tsmApi Tutorials Page

Martin Reddy, <reddy@ai.sri.com> / Yvan Leclerc, <leclerc@ai.sri.com>
Last modified: Wed Aug 23 00:45:27 PDT 2000