Girder Configuration Options ============================ General Plugin Settings ----------------------- There are some general plugin settings that affect large_image as a Girder plugin. These settings can be accessed by an Admin user through the ``Admin Console`` / ``Plugins`` and selecting the gear icon next to ``Large image``. YAML Configuration Files ------------------------ Some settings can be specified per-folder tree using yaml files. For these settings, if the configuration file exists in the current folder it is used. If not, the parent folders are checked iteratively up to the parent collection or user. If no configuration file is found, the ``.config`` folder in the collection or user is checked for the file. Lastly, the ``Configuration Folder`` specified on the plugin settings page is checked for the configuration file. The configuration files can have different configurations based on the user's access level and group membership. The yaml file has the following structure: :: --- # most settings are key-value pairs, where the value could be another # dictionary with keys and values, lists, or other valid data. : # The access key is special access: # logged in users get these settings user: # If the value is a dictionary and the key matches a key at the base # level, then the values are combined. To completely replace the base # value, add the special key "__all__" and set it's value to true. : # admin users get these settings admin: : # The groups key specifies that specific user groups have distinct settings groups: : : # groups can specify access based on user or admin, too. access: ... # If __inherit__ is true, then merge this config file with the next config # file in the parent folder hierarchy. __inherit__: true .large_image_config.yaml ~~~~~~~~~~~~~~~~~~~~~~~~ Items Lists ........... This is used to specify how items appear in item lists. There are two settings, one for folders in the main Girder UI and one for folders in dialogs (such as when browsing in the file dialog). :: --- # If present, show a table with column headers in item lists itemList: # layout does not need to be specified. layout: # The default layout is a list. This can optionally be "grid" mode: grid # max-width is only used in grid mode. It is the maximum width in # pixels for grid entries. It defaults to 250. max-width: 250 # show these columns in order from left to right. Each column has a # "type" and "value". It optionally has a "title" used for the column # header, and a "format" used for searching and filtering. The "label", # if any, is displayed to the left of the column value. This is more # useful in an grid view than in a column view. columns: - # The "image" type's value is either "thumbnail" or the name of an # associated image, such as "macro" or "label". type: image value: thumbnail title: Thumbnail # The maximum size of images can be specified. It defaults to 160 x # 100. It will always maintain the original aspect ratio. width: 250 height: 250 - type: image value: label title: Slide Label - # The "record" type is from the default item record. The value is # one of "name", "size", or "controls". type: record value: name - type: record value: size - type: record value: controls - # The "metadata" type is taken from the item's "meta" contents. It # can be a nested key by using dots in its name. type: metadata value: Stain # "format" can be "text", "number", "category". Other values may be # specified later. format: text - type: metadata # This will get "Label" from the first entry in array "gloms" value: gloms.0.Label title: First Glom Label - type: metadata # You can use some javascript-like properties, such as .length for # the length of arrays. value: gloms.length title: Number of Gloms # You can have this value be populated for just some of the items by # specifying an "only" list. Each entry in the only list must have # the "type" and "value" as per the column it is filtering on, plus a # "match" value that is used as a case-insensitive RegExp. All such # limits must match to show the value. only: - type: record value: name # only show this for items whose names end with ".svs". match: "\\.svs$" # You can edit metadata in a item list by adding the edit: true entry # and the options from the itemMetadata records that are detailed # below. In this case, edits to metadata that validate are saved # immediately. - type: metadata value: userstain title: User Stain label: User Stain edit: true # description is used as both a tooltip and as placeholder text description: Staining method # if required is true, the value can't be empty required: true # If a regex is specified, the value must match # regex: '^(Eosin|H&E|Other)$' # If an enum is specified, the value is set via a dropdown select box enum: - Eosin - H&E - Other # If a default is specified, if the value is unset, it will show this # value in the control default: H&E defaultSort: # The default lists a sort order for sortable columns. This must have # type, value, and dir for each entry, where dir is either "up" or # "down". - type: metadata value: Stain dir: up - type: record value: name dir: down itemListDialog: # Show these columns columns: - type: image value: thumbnail title: Thumbnail - type: record value: name - type: metadata value: Stain format: text - type: record value: size If there are no large images in a folder, none of the image columns will appear. Item Metadata ............. By default, item metadata can contain any keys and values. These can be given better titles and restricted in their data types. :: --- # If present, offer to add these specific keys and restrict their datatypes itemMetadata: - # value is the key name within the metadata value: stain # title is the displayed titles title: Stain # description is used as both a tooltip and as placeholder text description: Staining method # if required is true, the delete button does not appear required: true # If a regex is specified, the value must match # regex: '^(Eosin|H&E|Other)$' # If an enum is specified, the value is set via a dropdown select box enum: - Eosin - H&E - Other # If a default is specified, when the value is created, it will show # this value in the control default: H&E - value: rating # type can be "number", "integer", or "text" (default) type: number # minimum and maximum are inclusive minimum: 0 maximum: 10 # Exclusive values can be specified instead # exclusiveMinimum: 0 # exclusiveMaximum: 10 Image Frame Presets .................... This is used to specify a list of presets for viewing images in the folder. Presets can be customized and saved in the GeoJS Image Viewer. To retrieve saved presets, use http://[serverURL]/api/v1/item/[itemID]/internal_metadata/presets. You can convert the response to YAML and paste it into the ``imageFramePresets`` key in your config file. Each preset can specify a name, a view mode, an image frame, and style options. - The name of a preset can be any string which uniquely identifies the preset. - There are four options for mode: - Frame control - id: 0 - name: Frame - Axis control - id: 1 - name: Axis - Channel Compositing - id: 2 - name: Channel Compositing - Band Compositing - id: 3 - name: Band Compositing - The frame of a preset is a 0-based index representing a single frame in a multiframe image. For single-frame images, this value will always be 0. For channel compositing, each channel will have a ``framedelta`` value which represents distance from this base frame value. The result of channel compositing is multiple frames (calculated via framedelta) composited together. - The style of a preset is a dictionary with a schema similar to the [style schema for tile retrieval](tilesource_options.rst#style). The value for a preset's style consists of a band definition, where each band may have the following: - ``band``: A 1-based index of a band within the current frame - ``framedelta``: An integer representing distance from the current frame, used for compositing multiple frames together - ``palette``: A hexadecimal string beginning with "#" representing a color to stain this frame - ``min``: The value to map to the first palette value - ``max``: The value to map to the last palette value - ``autoRange``: A shortcut for excluding a percentage from each end of the value distribution in the image. Express as a float. The YAML below includes some example presets. :: --- # If present, each preset in this list will be added to the preset list # of every image in the folder for which the preset is applicable imageFramePresets: - name: Frame control - Frame 4 frame: 4 mode: id: 0 name: Frame - name: Axis control - Frame 25 frame: 25 mode: id: 1 name: Axis - name: 3 channels frame: 0 mode: id: 2 name: Channel Compositing style: bands: - framedelta: 0 palette: "#0000FF" - framedelta: 1 palette: "#FF0000" - framedelta: 2 palette: "#00FF00" - name: 3 bands frame: 0 mode: id: 3 name: Band Compositing style: bands: - band: 1 palette: "#0000FF" - band: 2 palette: "#FF0000" - band: 3 palette: "#00FF00" - name: Channels with Min and Max frame: 0 mode: id: 2 name: Channel Compositing style: bands: - min: 18000 max: 43000 framedelta: 0 palette: "#0000FF" - min: 18000 max: 43000 framedelta: 1 palette: "#FF0000" - min: 18000 max: 43000 framedelta: 2 palette: "#00FF00" - min: 18000 max: 43000 framedelta: 3 palette: "#FFFF00" - name: Auto Ranged Channels frame: 0 mode: id: 2 name: Channel Compositing style: bands: - autoRange: 0.2 framedelta: 0 palette: "#0000FF" - autoRange: 0.2 framedelta: 1 palette: "#FF0000" - autoRange: 0.2 framedelta: 2 palette: "#00FF00" - autoRange: 0.2 framedelta: 3 palette: "#FFFF00" - autoRange: 0.2 framedelta: 4 palette: "#FF00FF" - autoRange: 0.2 framedelta: 5 palette: "#00FFFF" - autoRange: 0.2 framedelta: 6 palette: "#FF8000" Image Frame Preset Defaults ........................... This is used to specify a list of preset defaults, in order of precedence. These presets are to be automatically applied to an image in this folder if they are applicable. In the case that a preset is not applicable to an image, the next item in this list will be used. ** Important: the presets named in this list must have corresponding entries in the ``imageFramePresets`` configuration, else this configuration will have no effect. ** :: --- # The preset named "Primary Preset" will be applied to all images in this folder. # Any images for which "Primary Preset" does not apply will have "Secondary Preset" applied. # Any images for which neither "Primary Preset" nor "Secondary Preset" apply will have "Tertiary Preset" applied. imageFramePresetDefaults: - name: Primary Preset - name: Secondary Preset - name: Tertiary Preset :: --- # This example would be used with the example for ``imageFramePresets`` shown above. # Images with 7 or more channels would use "Auto Ranged Channels" # Images with fewer than 7 but at least 4 channels would use "Channels with Min and Max" # Images with 3 channels would use "3 channels" # Images with fewer than 3 channels would not have a default preset applied. imageFramePresetDefaults: - name: Auto Ranged Channels - name: Channels with Min and Max - name: 3 channels Editing Configuration Files --------------------------- Some file types can be edited on their item page. This is detected based on the mime type associated with the file: ``application/json`` for json files and ``text/yaml`` or ``text/x-yaml`` for yaml files. If a user has enough permissions, these can be modified and saved. Note that this does not alter imported files; rather, on save it will create a new file in the assetstore and use that; this works fine for using the configuration files. For admins, there is also support for the ``application/x-girder-ini`` mime type for Girder configuration files. This has a special option to replace the existing Girder configuration and restart the server and should be used with due caution.