Function:     SETWCSBOX

Purpose:      SETWCSBOX define a box inside/around a subset (No user
              interaction)

Category:     USER IO, PHYSICAL COORDINATES

File:         ioutils.py

Author:       M.G.R. Vogelaar

Use:          boxtxt = "2h10m30s 60d32m2.7s D 2 arcmin 3 arcmin"
              blo, bhi = gset.setwcsbox(boxtxt, checklimits=True)

              gset          Object of class Set for which a box should be defined.
              boxtxt        Box specification as a string
              checklimits   Boolean. If True, 'boxtxt' is not allowed to specify
                            regions beyond the data regions.

              blo
              bhi     Two lists with coordinates which set the axes limits of
                      the input subset.
                      The coordinates are sorted so that 'blo' represents the
                      lower limits and 'bhi' the upper limits.
                      Note that also the Set object (gset) is updated. 
                      Therefore you can retrieve the limits also by accessing
                      attributes gset.blo, gset.bhi

Description:  Read also the description for the interactive routine WCSBOX

Notes:        In most situations the conversion between grids and world
              coordinates is independent of the subset. E.g. in a sequence
              of channel maps, each RA,Dec image represents the same
              coordinate system.
              However, when we create subsets with only one spatial axis,
              then the matching spatial coordinate depends on the selected
              subset (e.g. with XV maps). Here we follow the implementation
              in gdsbox.c. That is, only the first subset is used for
              coordinate transformations.

Examples:     boxtxt = "-10 -10 20 30"
              boxtxt = "0 0 D 30 50"
              boxtxt = "2h10m30s 60d32m2.7s D 10 10"
              boxtxt = "2h10m30s 60d32m2.7s D 2 arcmin 3 arcmin"
               
              blo, bhi = gset.setwcsbox(boxtxt)
              

Updates:      Sep 28, 2012: VOG, Document created.