The TMAP file format

The TMAP format contains a description of image layers, markers, regions, and settings. It is highly recommended to create .tmap files by saving projects from TissUUmaps, but you can also edit the files manually to add or change projects’ settings, or generate them as exported data from other software for import in TissUUmaps.

For more information on the TMAPS format, see the TissUUmaps-schema github page.

The TMAP format uses JSON, with the following specifications:

type	object
properties
schemaVersion	type	string
	default	1.2
filename	Name of the project.
	default	null
	anyOf	type	string
		type	null
link	Url to a publication or other external resource: a click on the filename will open this link.
	default	null
	anyOf	type	string
		type	null
layers	type	array
	default
	items	Layer
layerOpacities	type	object
	default
	additionalProperties	type	number
layerVisibilities	type	object
	default
	additionalProperties	type	boolean
layerFilters	Image filters to be applied to pixels in image layers.
	type	object
	default
	additionalProperties	type	array
		items	LayerFilter
filters	List of filters shown as active filters in the GUI under the Image layers tab.
	type	array
	default	Saturation
		Brightness
		Contrast
	items	Filter
compositeMode	Mode defining how image layers will be merged (composited) with each other. Valid string values are ‘source-over’ and ‘lighter’, which correspond to ‘Channels’ and ‘Composite’ in the GUI.
	default	source-over
	allOf	CompositeMode
collectionLayout	Options to be passed to OpenSeadragon arrange method when in collectionmode. See (https://openseadragon.github.io/docs/OpenSeadragon.World.html#arrange)
	default	null
	anyOf	CollectionLayout
		type	null
mpp	The image scale in Microns Per Pixels. If not null, then adds a scale bar to the viewer. Set to 0 to display the scale bar in pixels.
	default	null
	anyOf	type	number
		type	null
boundingBox	Bounding box used to set initial zoom and pan on the view when loading the project.
	default	null
	anyOf	BoundingBox
		type	null
rotate	Angle of rotation of the view in degrees. Only multiples of 90 degrees are supported.
	type	integer
	default	0
markerFiles	type	array
	default
	items	MarkerFile
regions	GeoJSON object.
	type	object
	default
regionFile	[Deprecated] GeoJSON region file loaded on project initialization. Use regionFiles instead.
	default	null
	anyOf	type	string
		type	null
regionFiles	type	array
	default
	items	RegionFile
plugins	List of plugins to load with the project.
	type	array
	default
	items	type	string
hideTabs	Hide tabs of markers dataset. Only use when you have a unique marker tab.
	type	boolean
	default	False
hideChannelRange	Hide input range of channels. Only use when you have a unique image layer.
	type	boolean
	default	False
hideNavigator	Hide navigator of the viewer.
	type	boolean
	default	False
collectionMode	If true, then the viewer will be in collection mode, which puts all layers in a grid next to each other.
	type	boolean
	default	False
backgroundColor	Background color of the viewer.
	default	null
	anyOf	type	string
		type	null
menuButtons	List of menu items to be added to the menu bar.
	default	null
	anyOf	type	array
		items	menuButton
		type	null
settings	type	array
	default
	items	Setting
additionalProperties	False

BoundingBox

type	object
properties
x	Left coordinate of the bounding box in viewport coordinate.
	type	number
y	Top coordinate of the bounding box in viewport coordinate.
	type	number
width	Width of the bounding box in viewport coordinate.
	type	number
height	Height of the bounding box in viewport coordinate.
	type	number
additionalProperties	False

CollectionLayout

type	object
properties
immediately	Whether to animate to the new arrangement.
	default	False
	anyOf	type	boolean
		type	null
layout	See collectionLayout in OpenSeadragon.Options.
	default	null
	anyOf	LayoutAxis
		type	null
rows	See collectionRows in OpenSeadragon.Options.
	default	null
	anyOf	type	integer
		type	null
columns	See collectionColumns in OpenSeadragon.Options.
	default	null
	anyOf	type	integer
		type	null
tileSize	See collectionTileSize in OpenSeadragon.Options.
	default	null
	anyOf	type	number
		type	null
tileMargin	See collectionTileMargin in OpenSeadragon.Options.
	default	null
	anyOf	type	number
		type	null
additionalProperties	False

CompositeMode

type	string
enum	source-over, lighter, darken, source-atop, source-in, source-out, destination-over, destination-atop, destination-in, destination-out, copy, xor, multiply, screen, overlay, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, hue, saturation, color, luminosity

DropdownOption

type	object
properties
optionName	Name displayed in the dropdown menu.
	type	string
name	Name of the tab to be loaded when the option is selected.
	type	string
additionalProperties	True

ExpectedHeader

type	object
properties
X	Name of CSV column to use as X-coordinate.
	type	string
Y	Name of CSV column to use as Y-coordinate.
	type	string
gb_col	Name of CSV column to use as key to group markers by.
	default	null
	anyOf	type	string
		type	null
gb_name	Name of CSV column to display for groups instead of group key.
	default	null
	anyOf	type	string
		type	null
cb_cmap	Name of D3 color scale to be used for color mapping.
	default	null
	anyOf	type	string
		type	null
cb_col	Name of CSV column containing scalar values for color mapping or hexadecimal RGB colors in format ‘#ff0000’.
	default	null
	anyOf	type	string
		type	null
cb_gr_dict	JSON string specifying a custom dictionary for mapping group keys to group colors. Example: "{'key1': '#ff0000', 'key2': '#00ff00', 'key3': '#0000ff'}".
	default
	anyOf	type	string
		type	object
		type	array
		items	type	string
scale_col	Name of CSV column containing scalar values for changing the size of markers.
	default	null
	anyOf	type	string
		type	null
scale_factor	Numerical value for a fixed scale factor to be applied to markers.
	type	number
	default	1.0
coord_factor	Numerical value for a fixed scale factor to be applied to marker coordinates.
	type	number
	default	1.0
pie_col	Name of CSV column containing data for pie chart sectors. TissUUmaps expects labels and numerical values for sectors to be separated by ‘:’ characters in the CSV column data.
	default	null
	anyOf	type	string
		type	null
pie_dict	JSON string specifying a custom dictionary for mapping pie chart sector indices to colors. Example: "{0: '#ff0000', 1: '#00ff00', 2: '#0000ff'}". If no dictionary is specified, TissUUmaps will use a default color palette instead.
	default
	anyOf	type	string
		type	object
		type	array
		items	type	string
shape_col	Name of CSV column containing a name or an index for marker shape.
	default	null
	anyOf	type	string
		type	null
shape_fixed	Name or index of a single fixed shape to be used for all markers.
	type	string
	default	cross
shape_gr_dict	JSON string specifying a custom dictionary for mapping group keys to group shapes. Example: "{'key1': 'square', 'key2': 'diamond', 'key3': 'triangle up'}".
	default
	anyOf	type	string
		type	object
		type	array
		items	type	string
edges_col	Name of CSV column containing a name or an index for marker edges in Network Diagram mode.
	default	null
	anyOf	type	string
		type	null
collectionItem_col	Name of CSV column containing a name or an index for marker collection items in Collection mode.
	default	null
	anyOf	type	string
		type	null
collectionItem_fixed	Name or index of a single fixed collection item to be used for all markers in Collection mode.
	default	0
	anyOf	type	string
		type	integer
opacity_col	Name of CSV column containing scalar values for opacities.
	default	null
	anyOf	type	string
		type	null
opacity	Numerical value for a fixed opacity factor to be applied to markers.
	type	number
	default	1.0
stroke_width	Numerical value for the marker stroke width.
	type	number
	default	2.5
sortby_col	Name of CSV column containing scalar values for sorting markers.
	default	null
	anyOf	type	string
		type	null
z_order	Numerical value of z-order to be used for all markers.
	type	number
	default	1.0
tooltip_fmt	Custom formatting string used for displaying metadata about a selected marker. See https://github.com/TissUUmaps/TissUUmaps/issues/2 for an overview of the grammer and keywords. If no string is specified, TissUUmaps will show default metadata depending on the context.
	type	string
	default
additionalProperties	False

ExpectedRadios

type	object
properties
cb_col	If markers should be colored by data in CSV column.
	type	boolean
	default	False
cb_gr	If markers should be colored by group.
	type	boolean
	default	True
cb_gr_rand	If group color should be generated randomly.
	type	boolean
	default	False
cb_gr_dict	If group color should be read from custom dictionary.
	type	boolean
	default	False
cb_gr_key	If group color should be generated from group key.
	type	boolean
	default	True
pie_check	If markers should be rendered as pie charts.
	type	boolean
	default	False
scale_check	If markers should be scaled by data in CSV column.
	type	boolean
	default	False
shape_col	If markers should get their shape from data in CSV column.
	type	boolean
	default	False
shape_gr	If markers should get their shape from group.
	type	boolean
	default	True
shape_gr_rand	If group shape should be generated randomly.
	type	boolean
	default	True
shape_gr_dict	If group shape should be read from custom dictionary.
	type	boolean
	default	False
shape_fixed	If a single fixed shape should be used for all markers.
	type	boolean
	default	False
opacity_check	If markers should get their opacities from data in CSV column.
	type	boolean
	default	False
_no_outline	If marker shapes should be rendered without outline.
	type	boolean
	default	False
no_fill	If marker shapes should be rendered without filling.
	type	boolean
	default	False
collectionItem_col	If markers should get their collection item from data in CSV column.
	type	boolean
	default	False
collectionItem_fixed	If a single fixed collection item should be used for all markers.
	type	boolean
	default	True
sortby_check	If markers should be sorted by data in CSV column.
	type	boolean
	default	False
sortby_desc_check	If markers should be sorted in descending order.
	type	boolean
	default	False
edges_check	If markers should be connected by edges in Network Diagram mode.
	type	boolean
	default	False
additionalProperties	False

Filter

type	string
enum	Color, Brightness, Exposure, Hue, Contrast, Vibrance, Noise, Saturation, Gamma, Invert, Greyscale, Threshold, Erosion, Dilation, SplitChannel, Colormap

Layer

type	object
properties
name	Name of the image layer
	type	string
tileSource	Relative path to an image file in a supported format.
	type	string
x	Left coordinate of the image in viewport coordinate.
	default	null
	anyOf	type	number
		type	null
y	Top coordinate of the image in viewport coordinate.
	default	null
	anyOf	type	number
		type	null
rotation	Rotation of the image in degrees.
	default	null
	anyOf	type	number
		type	null
flip	Flip the image horizontally.
	type	boolean
	default	False
scale	Scale of the image.
	default	null
	anyOf	type	number
		type	null
clip	Bounding box used to clip image in image pixel coordinate. If not specified, the whole image is shown.
	default	null
	anyOf	LayerClip
		type	null
additionalProperties	False

LayerClip

type	object
properties
x	Left coordinate of the clip in image pixel coordinate.
	type	number
y	Top coordinate of the clip in image pixel coordinate.
	type	number
w	Width of the clip in image pixel coordinate.
	type	number
h	Height of the clip in image pixel coordinate.
	type	number
additionalProperties	False

LayerFilter

type	object
properties
name	Filter name.
	allOf	Filter
value	Filter parameter.
	anyOf	type	string
		type	boolean
		type	integer
		type	number
additionalProperties	False

LayoutAxis

type	string
enum	horizontally, vertically

MarkerFile

type	object
properties
comment	Optional description text shown next to marker button.
	default	null
	anyOf	type	string
		type	null
name	Name of marker tab.
	default	null
	anyOf	type	string
		type	null
autoLoad	If the CSV file for the marker dataset should be automatically loaded when the TMAP project is opened. If this is false, the user instead has to click on the marker button in the GUI to load the dataset. If this is an integer, the n-th marker dataset is automatically loaded.
	default	False
	anyOf	type	boolean
		type	integer
hideSettings	Hide markers’ settings and add a toggle button instead.
	type	boolean
	default	False
uid	A unique identifier used internally by TissUUmaps to reference the marker dataset.
	default	null
	anyOf	type	string
		type	null
expectedHeader	ExpectedHeader
expectedRadios	ExpectedRadios
path	Relative file path to CSV file in which marker data is stored. If array of string, then a dropdown is created instead of a button.
	anyOf	type	string
		type	array
		items	type	string
dropdownOptions	List of dropdown options. Each option is a dictionary with the keys ‘title’ and ‘path’.
	default	null
	anyOf	type	array
		items	DropdownOption
		type	null
settings	type	array
	default
	items	Setting
fromButton	If this is an integer, then the marker dataset is loaded from the n-th marker button.
	default	null
	anyOf	type	integer
		type	null
additionalProperties	False

RegionFile

type	object
properties
comment	Optional description text shown next to region button.
	default	null
	anyOf	type	string
		type	null
autoLoad	If the regions should be automatically loaded when the TMAP project is opened. If this is false, the user instead has to click on the region button in the GUI to load the regions.
	type	boolean
	default	False
path	Relative file path to GeoJSON file in which marker data is stored. If array of string, then a dropdown is created instead of a button.
	anyOf	type	string
		type	array
		items	type	string
settings	type	array
	default
	items	Setting
additionalProperties	False

Setting

type	object
properties
module	Module where the function or property lies.
	type	string
function	Function or property of the given module.
	type	string
value
additionalProperties	False

menuButton

type	object
properties
text	Text of the menu item. If list, then a nested menu is created.
	anyOf	type	array
		items	type	string
		type	string
url	Url of the menu item.
	type	string
additionalProperties	False

Example of a .tmap file

{
    "filename": "TissUUmaps_Example.tmap",
    "layers": [
        {
            "name": "Round1_A.tif",
            "tileSource": "images/Round1_A.tif.dzi"
        },
        {
            "name": "Round1_C.tif",
            "tileSource": "images/Round1_C.tif.dzi"
        }
    ],
    "layerOpacities": {
        "0": "1",
        "1": "1"
    },
    "layerVisibilities": {
        "0": true,
        "1": false,
    },
    "layerFilters": {
        "0": [
            {
                "name": "Color",
                "value": "0,100,0"
            }
        ],
        "1": [
            {
                "name": "Color",
                "value": "0,100,0"
            }
        ]
    },
    "filters": [
        "Color"
    ],
    "compositeMode": "lighter",
    "markerFiles": [
        {
            "autoLoad": false,
            "comment": "",
            "expectedHeader": {
                "X": "global_x",
                "Y": "global_y",
                "cb_cmap": "",
                "cb_col": "null",
                "cb_gr_dict": "",
                "gb_col": "Gene",
                "gb_name": "",
                "opacity": "1",
                "opacity_col": "null",
                "pie_col": "null",
                "pie_dict": "",
                "scale_col": "null",
                "scale_factor": "0.5",
                "shape_col": "null",
                "shape_fixed": "cross",
                "shape_gr_dict": "",
                "tooltip_fmt": ""
            },
            "expectedRadios": {
                "cb_col": false,
                "cb_gr": true,
                "cb_gr_dict": false,
                "cb_gr_key": true,
                "cb_gr_rand": false,
                "pie_check": false,
                "scale_check": false,
                "shape_col": false,
                "shape_fixed": false,
                "shape_gr": true,
                "shape_gr_dict": false,
                "shape_gr_rand": true,
                "opacity_check": false
            },
            "name": " markers",
            "path": "./istdeco_codes_n.csv",
            "title": "Download markers",
            "uid": "uniquetab"
        }
    ],
    "regions": {},
    "plugins": [
        "Spot_Inspector"
    ],
    "hideTabs": true,
    "settings": []
}