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
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. <key>: <value> # 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. <key>: <value> # admin users get these settings admin: <key>: <value> # The groups key specifies that specific user groups have distinct settings groups: <group name>: <key>: <value> # 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
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 there are no large images in a folder, none of the image columns will appear.
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:
name: Channel Compositing
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
framedeltavalue 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/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.