API for datatypes derived from imagetile (github.com/janelia-flyem/dvid/datatype/imagetile)
=====================================================================================

Note: UUIDs referenced below are strings that may either be a unique prefix of a
hexadecimal UUID string (e.g., 3FA22) or a branch leaf specification that adds
a colon (":") followed by the case-dependent branch name.  In the case of a
branch leaf specification, the unique UUID prefix just identifies the repo of
the branch, and the UUID referenced is really the leaf of the branch name.
For example, if we have a DAG with root A -> B -> C where C is the current
HEAD or leaf of the "master" (default) branch, then asking for "B:master" is
the same as asking for "C".  If we add another version so A -> B -> C -> D, then
references to "B:master" now return the data from "D".

Command-line:

$ dvid repo <UUID> new imagetile <data name> <settings...>

	Adds multiresolution XY, XZ, and YZ imagetile from Source to repo with specified UUID.

	Example:

	$ dvid repo 3f8c new imagetile myimagetile source=mygrayscale format=jpg

	Arguments:

	UUID           Hexadecimal string with enough characters to uniquely identify a version node.
	data name      Name of data to create, e.g., "mygrayscale"
	settings       Configuration settings in "key=value" format separated by spaces.

	Configuration Settings (case-insensitive keys)

	Format         "lz4", "jpg", or "png" (default).  In the case of "lz4", decoding/encoding is done at
					  tile request time and is a better choice if you primarily ask for arbitrary sized images
					  (via GET .../raw/... or .../isotropic/...) instead of tiles (via GET .../tile/...)
	Versioned      "true" or "false" (default)
	Source         Name of uint8blk data instance if using the tile "generate" command below.
	Placeholder    Bool ("false", "true", "0", or "1").  Return placeholder tile if missing.


$ dvid node <UUID> <data name> generate [settings]
$ dvid -stdin node <UUID> <data name> generate [settings] < config.json

	Generates multiresolution XY, XZ, and YZ imagetile from Source to repo with specified UUID.
	The resolutions at each scale and the dimensions of the tiles are passed in the configuration
	JSON.  Only integral multiplications of original resolutions are allowed for scale.  If you
	want more sophisticated processing, post the imagetile tiles directly via HTTP.  Note that
	the generated tiles are aligned in a grid having (0,0,0) as a top left corner of a tile, not
	tiles that start from the corner of present data since the data can expand.

	If not tile spec file is used, a default tile spec is generated that will cover the 
	extents of the source data.

	Example:

	$ dvid repo 3f8c myimagetile generate /path/to/config.json
	$ dvid -stdin repo 3f8c myimagetile generate xrange=100,700 planes="yz;0,1" < /path/to/config.json 

	Arguments:

	UUID            Hexadecimal string with enough characters to uniquely identify a version node.
	data name       Name of data to create, e.g., "mygrayscale".
	settings        Optional file name of tile specifications for tile generation.

	Configuration Settings (case-insensitive keys)

	planes          List of one or more planes separated by semicolon.  Each plane can be
					   designated using either axis number ("0,1") or xyz nomenclature ("xy").
					   Example:  planes="0,1;yz"
	zrange			Only render XY tiles containing pixels between this minimum and maximum in z.
	yrange			Only render XZ tiles containing pixels between this minimum and maximum in y.
	xrange			Only render YZ tiles containing pixels between this minimum and maximum in x.
	filename        Filename of JSON file specifying multiscale tile resolutions as below.

	Sample config.json:

	{
		"0": {  "Resolution": [10.0, 10.0, 10.0], "TileSize": [512, 512, 512] },
		"1": {  "Resolution": [20.0, 20.0, 20.0], "TileSize": [512, 512, 512] },
		"2": {  "Resolution": [40.0, 40.0, 40.0], "TileSize": [512, 512, 512] },
		"3": {  "Resolution": [80.0, 80.0, 80.0], "TileSize": [512, 512, 512] }
	}
	
 $ dvid repo <UUID> push <remote DVID address> <settings...>
 
		Push tiles to remote DVID.

		where <settings> are optional "key=value" strings:

		data=<data1>[,<data2>[,<data3>...]]
		
			If supplied, the transmitted data will be limited to the listed
			data instance names.
				
		filter=roi:<roiname>,<uuid>/tile:<plane>,<plane>
        
            Example: filter=roi:seven_column,38af/tile:xy,xz
		
			There are two usable filters for imagetile:
            The "roi" filter is followed by an roiname and a UUID for that ROI.
            The "tile" filter is followed by one or more plane specifications (xy, xz, yz).  
            If omitted all planes are pushed.
		
		transmit=[all | branch | flatten]

			The default transmit "all" sends all versions necessary to 
			make the remote equivalent or a superset of the local repo.
			
			A transmit "flatten" will send just the version specified and
			flatten the key/values so there is no history.
            
            A transmit "branch" will send just the ancestor path of the
            version specified.


	------------------

HTTP API (Level 2 REST):

GET  <api URL>/node/<UUID>/<data name>/help

	Returns data-specific help message.


GET  <api URL>/node/<UUID>/<data name>/info

	Retrieves characteristics of this tile data like the tile size and number of scales present.

	Example: 

	GET <api URL>/node/3f8c/myimagetile/info

	Arguments:

	UUID          Hexadecimal string with enough characters to uniquely identify a version node.
	data name     Name of imagetile data.


GET  <api URL>/node/<UUID>/<data name>/metadata

	Gets the resolution and expected tile sizes for stored tiles.   See the POST action on this endpoint
	for further documentation.

POST <api URL>/node/<UUID>/<data name>/metadata

	Sets the resolution and expected tile sizes for stored tiles.   This should be used in conjunction
	with POST to the tile endpoints to populate an imagetile data instance with externally generated
	data.  For example POST payload, see the sample config.json above in "generate" command line.

	Note that until metadata is set, any call to the "raw" or "isotropic" endpoints will return
	a status code 400 (Bad Request) and a message that the metadata needs to be set.

	Metadata should be JSON in the following format:
	{
		"MinTileCoord": [0, 0, 0],
		"MaxTileCoord": [5, 5, 4],
		"Levels": {
			"0": {  "Resolution": [10.0, 10.0, 10.0], "TileSize": [512, 512, 512] },
			"1": {  "Resolution": [20.0, 20.0, 20.0], "TileSize": [512, 512, 512] },
			"2": {  "Resolution": [40.0, 40.0, 40.0], "TileSize": [512, 512, 512] },
			"3": {  "Resolution": [80.0, 80.0, 80.0], "TileSize": [512, 512, 512] }
		}
	}

	where "MinTileCoord" and "MaxTileCoord" are the minimum and maximum tile coordinates,
	thereby defining the extent of the tiled volume when coupled with level "0" tile sizes.


GET  <api URL>/node/<UUID>/<data name>/tile/<dims>/<scaling>/<tile coord>[?noblanks=true]
POST
	Retrieves or adds tile of named data within a version node.  This GET call should be the fastest
	way to retrieve image data since internally it has already been stored in a pre-computed, optionally
	compression format, whereas arbitrary geometry calls require the DVID server to stitch images
	together.

	The returned image format is dictated by the imagetile encoding.  PNG tiles are returned
	if internal encoding is either lz4 or png.  JPG tiles are returned if internal encoding is JPG.
	The only reason to use lz4 for internal encoding is if the majority of endpoint use for
	the data instance is via the "raw" endpoint where many tiles need to be stitched before
	sending the requested image back.

	Note on POSTs: The data of the body in the POST is assumed to match the data instance's 
	chosen compression and tile sizes.  Currently, no checks are performed to make sure the
	POSTed data meets the specification.

	Example: 

	GET  <api URL>/node/3f8c/myimagetile/tile/xy/0/10_10_20
	POST <api URL>/node/3f8c/myimagetile/tile/xy/0/10_10_20

	Arguments:

	UUID          Hexadecimal string with enough characters to uniquely identify a version node.
	data name     Name of data to add.
	dims          The axes of data extraction in form "i_j_k,..."  Example: "0_2" can be XZ.
					Slice strings ("xy", "xz", or "yz") are also accepted.
	scaling       Value from 0 (original resolution) to N where each step is downres by 2.
	tile coord    The tile coordinate in "x_y_z" format.  See discussion of scaling above.

  	Query-string options:

  	noblanks	  (only GET) If true, any tile request for tiles outside the currently stored extents
  				  will return a blank image.


GET  <api URL>/node/<UUID>/<data name>/tilekey/<dims>/<scaling>/<tile coord>

	Retrieves the internal key for a tile of named data within a version node.  
	This lets external systems bypass DVID and store tiles directly into immutable stores.

	Returns JSON with "key" key and a hexadecimal string giving binary key.

	Example: 

	GET  <api URL>/node/3f8c/myimagetile/tilekey/xy/0/10_10_20

	Returns:
	{ "key": <hexadecimal string of key> }

	Arguments:

	UUID          Hexadecimal string with enough characters to uniquely identify a version node.
	data name     Name of data to add.
	dims          The axes of data extraction in form "i_j_k,..."  Example: "0_2" can be XZ.
					Slice strings ("xy", "xz", or "yz") are also accepted.
	scaling       Value from 0 (original resolution) to N where each step is downres by 2.
	tile coord    The tile coordinate in "x_y_z" format.  See discussion of scaling above.


GET  <api URL>/node/<UUID>/<data name>/raw/<dims>/<size>/<offset>[/<format>]

	Retrieves raw image of named data within a version node using the precomputed imagetile.
	By "raw", we mean that no additional processing is applied based on voxel resolutions
	to make sure the retrieved image has isotropic pixels.  For example, if an XZ image
	is requested and the image volume has X resolution 3 nm and Z resolution 40 nm, the
	returned image will be heavily anisotropic and should be scaled by 40/3 in Y by client.

	Example: 

	GET <api URL>/node/3f8c/myimagetile/raw/xy/512_256/0_0_100/jpg:80

	Arguments:

	UUID          Hexadecimal string with enough characters to uniquely identify a version node.
	data name     Name of data to add.
	dims          The axes of data extraction in form i_j.  Example: "0_2" can be XZ.
					Slice strings ("xy", "xz", or "yz") are also accepted.
					Note that only 2d images are returned for imagetiles.
	size          Size in voxels along each dimension specified in <dims>.
	offset        Gives coordinate of first voxel using dimensionality of data.
	format        "png", "jpg" (default: "png")
					jpg allows lossy quality setting, e.g., "jpg:80"

GET  <api URL>/node/<UUID>/<data name>/isotropic/<dims>/<size>/<offset>[/<format>]

	Retrieves isotropic image of named data within a version node using the precomputed imagetile.
	Additional processing is applied based on voxel resolutions to make sure the retrieved image 
	has isotropic pixels.  For example, if an XZ image is requested and the image volume has 
	X resolution 3 nm and Z resolution 40 nm, the returned image's height will be magnified 40/3
	relative to the raw data.

	Example: 

	GET <api URL>/node/3f8c/myimagetile/isotropic/xy/512_256/0_0_100/jpg:80

	Arguments:

	UUID          Hexadecimal string with enough characters to uniquely identify a version node.
	data name     Name of data to add.
	dims          The axes of data extraction in form i_j.  Example: "0_2" can be XZ.
					Slice strings ("xy", "xz", or "yz") are also accepted.
					Note that only 2d images are returned for imagetiles.
	size          Size in voxels along each dimension specified in <dims>.
	offset        Gives coordinate of first voxel using dimensionality of data.
	format        "png", "jpg" (default: "png")
					jpg allows lossy quality setting, e.g., "jpg:80"