### Install Dependencies

Source: https://github.com/girder/large_image/blob/master/docs/development.md

Commands to install packages and dependencies using pip.

```default
pip install -e . -r requirements-dev.txt
```

```default
pip install -e . -r requirements-dev-core.txt
```

```default
pip install -e . -r requirements-dev.txt --find-links https://girder.github.io/large_image_wheels
```

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

### Install Tox

Source: https://github.com/girder/large_image/blob/master/docs/development.md

Install the tox package for managing test environments.

```bash
pip install tox
```

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

### Install large_image with all options

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/large_image_examples.ipynb

Installs the large_image library with all available tile sources and dependencies. Use `--find-links` to specify a wheel repository. For a smaller installation, specify desired sources like [pil,rasterio,tifffile].

```python
# This will install large_image, including all sources and many other options
!pip install large_image[all] --find-links https://girder.github.io/large_image_wheels
# For a smaller set of tile sources, you could also do:
# !pip install large_image[pil,rasterio,tifffile]

# For maximum capabilities in Jupyter, also install ipyleaflet so you can
# view zoomable images in the notebook
!pip install 'ipyleaflet>=0.19'

# If you are accessing files on a Girder server, it is useful to install girder_client
!pip install girder_client
```

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

### Build and Serve Girder

Source: https://github.com/girder/large_image/blob/master/docs/development.md

Commands to build and start the Girder server.

```bash
girder build --dev
girder serve
```

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

### Install large_image dependencies

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/zarr_sink_example.ipynb

Install the necessary packages for Zarr support and interactive visualization in Jupyter.

```python
!pip install large_image[tiff,zarr,converter] --find-links https://girder.github.io/large_image_wheels

# For maximum capabilities in Jupyter, also install ipyleaflet so you can
# view zoomable images in the notebook
!pip install ipyleaflet
```

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

### Install large_image and dependencies

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/frame_viewer_example.ipynb

Install the necessary packages for tile source support and interactive visualization in Jupyter.

```python
!pip install large_image[tiff] 'ipyleaflet>=0.19' ipyvue --find-links=https://girder.github.io/large_image_wheels
```

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

### Install large-image-converter with pip

Source: https://github.com/girder/large_image/blob/master/utilities/converter/README.rst

Install the large-image-converter package using pip. The '[sources]' extra is optional and installs default large-image tile sources for additional metadata extraction and format support.

```bash
pip install large-image-converter[sources] --find-links https://girder.github.io/large_image_wheels
```

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

### Install large-image with all tile sources using Pip

Source: https://github.com/girder/large_image/blob/master/docs/index.md

Install the base large-image package and all available tile sources on Linux. This command requires specifying a wheelhouse for pre-built packages.

```bash
pip install large-image[all] --find-links https://girder.github.io/large_image_wheels
```

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

### Run MongoDB Container

Source: https://github.com/girder/large_image/blob/master/docs/development.md

Start a MongoDB instance locally using Docker for testing.

```bash
docker run -p 27017:27017 -d mongo:latest
```

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

### Install large-image with common tile sources using Pip

Source: https://github.com/girder/large_image/blob/master/docs/index.md

Use this command to install the base large-image package along with common tile sources. This is suitable for most use cases on Linux, OSX, or Windows.

```bash
pip install large-image[common]
```

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

### Get help for large_image_converter

Source: https://github.com/girder/large_image/blob/master/utilities/converter/README.rst

Display the full list of available options and commands for the large_image_converter tool.

```bash
large_image_converter --help
```

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

### Install large-image with Girder integration using Pip

Source: https://github.com/girder/large_image/blob/master/docs/index.md

Install large-image with all tile sources, Girder integration, and task support on Linux. This command is for users integrating large-image with a Girder instance.

```bash
pip install large-image[all] girder-large-image-annotation[tasks] --find-links https://girder.github.io/large_image_wheels
```

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

### Write image from multiple processes

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

This example demonstrates writing to a single image from multiple processes. It highlights the importance of adding a tile at the maximum position first to preallocate dimensions for frame axes.

```python
import large_image
import multiprocessing

# Important: Must be a pickleable function
def add_tile_to_source(tilesource, nparray, position):
    tilesource.addTile(
        nparray,
        **position
    )

source = large_image.new()
# Important: Maximum size must be allocated before any multiprocess concurrency
add_tile_to_source(source, np.zeros(1, 1, 3), dict(x=max_x, y=max_y, z=max_z))
# Also works with multiprocessing.ThreadPool, which does not need maximum size allocated first
with multiprocessing.Pool(max_workers=5) as pool:
    pool.starmap(
        add_tile_to_source,
        [(source, t, t_pos) for t, t_pos in tileset]
    )
source.write('/tmp/sample.zarr.zip', lossy=False)
```

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

### Install large-image-converter using Conda

Source: https://github.com/girder/large_image/blob/master/docs/index.md

Install the converter module for large-image using Conda. This module is also available on conda-forge.

```bash
conda install -c conda-forge large-image-converter
```

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

### Create a multiframe image with Zarr

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

This example demonstrates creating an image with multiple frames and axes (T, Z, Y, X, S) using the large-image-source-zarr. It shows how to add tiles with specific frame indices and values.

```python
import large_image

time_values = [0.5, 1.5, 2.5, 3.5]
z_values = [3, 6, 9]
tile_pos_values = [0, 1024, 2048, 3072, 4096]

source = large_image.new()
for t_index, t_value in enumerate(time_values):
    for z_index, z_value in enumerate(z_values):
        for y_value in tile_pos_values:
            for x_value in tile_pos_values:

                # tile is a numpy array with shape (1024, 1024, 3)
                # this shape corresponds to the following axes, respectively: (Y, X, S)
                tile = get_my_data_tile(x_value, y_value, z_value, t_value)

                source.addTile(
                    tile,
                    x_value,
                    y_value,
                    z=z_index,
                    time=t_index,

                    # z_value and t_value are optional parameters to store the
                    # true values at the provided z index and t index
                    z_value=z_value,
                    time_value=t_value,
                )
source.frameUnits = dict(t='ms', z='cm')

# The writer supports a variety of formats
source.write('/tmp/sample.zarr.zip', lossy=False)
```

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

### Install large-image using Conda

Source: https://github.com/girder/large_image/blob/master/docs/index.md

Install the base large-image package using Conda. This is an alternative to pip, especially useful for managing dependencies on non-Linux systems.

```bash
conda install -c conda-forge large-image
```

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

### Write a basic tiled image

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Use this snippet to write a tiled image from numpy arrays. Ensure a compatible tile source (e.g., zarr or vips) is installed. The zarr source is the default if both are present.

```python
import large_image

source = large_image.new()
for nparray, x, y in fancy_algorithm():
    # We could optionally add a mask to limit the output
    source.addTile(nparray, x, y)
source.write('/tmp/sample.tiff', lossy=False)
```

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

### Access Girder MongoDB

Source: https://github.com/girder/large_image/blob/master/docs/upgrade.md

Use this command to access the Girder database in a simple installation.

```default
mongo girder
```

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

### Install large-image-source-tiff using Conda

Source: https://github.com/girder/large_image/blob/master/docs/index.md

Install the TIFF tile source for large-image using Conda. This is another source module available on conda-forge.

```bash
conda install -c conda-forge large-image-source-tiff
```

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

### Define Image Frame Presets in YAML

Source: https://github.com/girder/large_image/blob/master/docs/girder_config_options.md

Example configuration for various image frame presets including frame control, axis control, channel compositing, and band compositing.

```default
---
# 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"
```

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

### Key - List of Key - Value Data Arrangement Example

Source: https://github.com/girder/large_image/blob/master/girder_annotation/docs/plottable.rst

Demonstrates a complex structure where a key contains a list of dictionaries, each with plottable data.

```json
"meta": {
  "nucleus": [
    {
      "radius": 4.5,
      "circularity": 0.9
    },
    {
      "radius": 5.5,
      "circularity": 0.86
    }
  ]
}
```

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

### Item List Configuration

Source: https://github.com/girder/large_image/blob/master/docs/girder_config_options.md

Example of a YAML configuration snippet for specifying how items appear in item lists, applicable to both the main Girder UI and dialogs.

```yaml
---

```

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

### Key-List of Key-Value Data Arrangement

Source: https://github.com/girder/large_image/blob/master/docs/plottable.md

Example of a 'meta' dictionary where a key maps to a list of objects, each containing key-value pairs.

```default
"meta": {
  "nucleus": [
    {
      "radius": 4.5,
      "circularity": 0.9
    },
    {
      "radius": 5.5,
      "circularity": 0.86
    },
    {
      "radius": 5.1,
      "circularity": 0.92
    }
  ]
}
```

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

### Configure Girder Plugin Settings

Source: https://github.com/girder/large_image/blob/master/docs/config_options.md

Settings for the Girder plugin can be specified in the `girder.cfg` file under the `[large_image]` section. This example shows common cache and size limit configurations.

```ini
[large_image]
# cache_backend, used for caching tiles, is either "memcached" or "python"
cache_backend = "python"
# 'python' cache can use 1/(val) of the available memory
cache_python_memory_portion = 32
# 'memcached' cache backend can specify the memcached server.
# cache_memcached_url may be a list
cache_memcached_url = "127.0.0.1"
cache_memcached_username = None
cache_memcached_password = None
# The tilesource cache uses the lesser of a value based on available file
# handles, the memory portion, and the maximum (if not 0)
cache_tilesource_memory_portion = 8
cache_tilesource_maximum = 0
# The PIL tilesource won't read images larger than the max small images size
max_small_image_size = 4096
# The bioformats tilesource won't read files that end in a comma-separated
# list of extensions
source_bioformats_ignored_names = r'(^[!.]*|\.(jpg|jpeg|jpe|png|tif|tiff|ndpi))$'
# The maximum size of an annotation file that will be ingested into girder
# via direct load
max_annotation_input_file_length = 1 * 1024 ** 3
```

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

### Sample Annotation Structure

Source: https://github.com/girder/large_image/blob/master/girder_annotation/docs/annotations.rst

A comprehensive example of a valid annotation, showcasing various element types like points, arrows, circles, rectangles, ellipses, polylines, and rectangle grids.

```json
{
    "name": "AnnotationName",
    "description": "This is a description",
    "attributes": {
      "key1": "value1",
      "key2": ["any", {"value": "can"}, "go", "here"]
    },
    "elements": [{
      "type": "point",
      "label": {
        "value": "This is a label",
        "visibility": "hidden",
        "fontSize": 3.4
      },
      "lineColor": "#000000",
      "lineWidth": 1,
      "center": [123.3, 144.6, -123]
    },{
      "type": "arrow",
      "points": [
        [5,6,0],
        [-17,6,0]
      ],
      "lineColor": "rgba(128, 128, 128, 0.5)"
    },{
      "type": "circle",
      "center": [10.3, -40.0, 0],
      "radius": 5.3,
      "fillColor": "#0000fF",
      "lineColor": "rgb(3, 6, 8)"
    },{
      "type": "rectangle",
      "center": [10.3, -40.0, 0],
      "width": 5.3,
      "height": 17.3,
      "rotation": 0,
      "fillColor": "rgba(0, 255, 0, 1)"
    },{
      "type": "ellipse",
      "center": [3.53, 4.8, 0],
      "width": 15.7,
      "height": 7.1,
      "rotation": 0.34,
      "fillColor": "rgba(128, 255, 0, 0.5)"
    },{
      "type": "polyline",
      "points": [
        [5,6,0],
        [-17,6,0],
        [56,-45,6]
      ],
      "closed": true
    },{
      "type": "rectanglegrid",
      "id": "0123456789abcdef01234567",
      "center": [10.3, -40.0, 0],
      "width": 5.3,
      "height": 17.3,
      "rotation": 0,
      "widthSubdivisions": 3,
      "heightSubdivisions": 4
    }]
  }
```

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

### Key-Value Data Arrangement

Source: https://github.com/girder/large_image/blob/master/docs/plottable.md

Example of a 'meta' dictionary containing simple key-value pairs for plottable data.

```default
"meta": {
  "nucleus_radius": 4.5,
  "nucleus_circularity": 0.9
}
```

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

### Key-Value List Data Arrangement

Source: https://github.com/girder/large_image/blob/master/docs/plottable.md

Example of a 'meta' dictionary with keys mapping to lists of values for plottable data.

```default
"meta": {
  "nucleus_radius": [4.5, 5.5, 5.1],
  "nucleus_circularity": [0.9, 0.86, 0.92]
}
```

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

### Configure Item Metadata Fields

Source: https://github.com/girder/large_image/blob/master/docs/girder_config_options.md

Defines specific metadata fields for items, including their display titles, descriptions, data types, and validation rules like regex or enums. This example shows configuration for 'stain' and 'rating' fields.

```yaml
---
# 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

```

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

### Get Tile with Specific Encoding

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Retrieve a tile from the image, ensuring a specific encoding format (e.g., PNG) by specifying it when opening the source. This guarantees the tile's format for caching consistency.

```python
import large_image
source = large_image.open('sample.tiff', encoding='PNG')
tile0 = source.getTile(0, 0, 0)
# tile is now guaranteed to be a PNG
```

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

### Get Geospatial Region with GCPs

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Extract a region from a non-georeferenced image by providing ground control points (GCPs) and target projection coordinates. Requires 'pyproj' and 'rasterio' to be installed. Additional arguments are passed to 'getRegion'.

```python
import large_image
source = large_image.open('sample.tiff')

source_projection = 'epsg:3857'
source_gcps = [
    # covers downtown DC
    (-8578909.8696,4704125.8132, 0, 0),
    (-8571075.0742,4710164.3385, source.sizeX, source.sizeY),
]
target_projection = 'epsg:4326'
target_region = {
    # covers US Capitol lot
    'left': -77.015104,
    'top': 38.887642,
    'right': -77.005877,
    'bottom': 38.892235,
}
getRegion_kwargs = dict(
    frame=0,
    format=large_image.constants.TILE_FORMAT_NUMPY,
)
nparray, mime_type = source.getGeospatialRegion(
    source_projection, source_gcps, target_projection, target_region, **getRegion_kwargs
)
```

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

### Initialize Map from Remote Tile Server

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/large_image_examples.ipynb

Configure a map using custom metadata and a URL template for slippy-map style tile servers.

```python
# There can be additional items in the metadata, but this is minimum required.
remoteMetadata = {
  'levels': 10,
  'sizeX': 95758,
  'sizeY': 76873,
  'tileHeight': 256,
  'tileWidth': 256,
}
remoteUrl = 'https://demo.kitware.com/histomicstk/api/v1/item/5bbdeec6e629140048d01bb9/tiles/zxy/{z}/{x}/{y}?encoding=PNG'

map4 = large_image.tilesource.jupyter.Map(metadata=remoteMetadata, url=remoteUrl)
map4
```

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

### Initialize Girder Client

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/large_image_examples.ipynb

Sets up a connection to a remote Girder server using the GirderClient.

```python
import girder_client

gc1 = girder_client.GirderClient(apiUrl='https://data.kitware.com/api/v1')
```

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

### Configure Development Environment

Source: https://github.com/girder/large_image/blob/master/docs/development.md

Commands to create and activate a development environment using tox.

```bash
tox --devenv /my/env/path -e dev
```

```bash
. /my/env/path/bin/activate
```

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

### Execute Tests and Documentation Builds

Source: https://github.com/girder/large_image/blob/master/docs/development.md

Commands to run test suites or build documentation using tox.

```bash
tox -e test-py39,lint,lintclient
```

```bash
tox -e core-py39,lint
```

```bash
tox -e docs
```

```bash
tox -e core-py39 -- -k testFromTiffRGBJPEG
```

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

### Install large-image-source-gdal using Conda

Source: https://github.com/girder/large_image/blob/master/docs/index.md

Install the GDAL tile source for large-image using Conda. This is one of the source modules available on conda-forge.

```bash
conda install -c conda-forge large-image-source-gdal
```

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

### Process tiles and write to sink

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/zarr_sink_example.ipynb

Initialize a new sink and iterate through tiles to apply processing and save results.

```python
# create a sink, which is an instance of ZarrFileTileSource and has no data
sink = large_image.new()

# compare three different footprint sizes for processing algorithm
# computing the processed image takes about 1 minute for each value
footprint_sizes = [1, 10, 50]
print(f'Processing image for {len(footprint_sizes)} frames.')

# create a frame for each processed result
for i, footprint_size in enumerate(footprint_sizes):
    print('Processing image with footprint_size = ', footprint_size)
    # iterate through tiles, getting numpy arrays for each tile
    for tile in source.tileIterator(format='numpy'):
        # for each tile, run some processing algorithm
        t = tile['tile']
        processed_tile = process_tile(t, footprint_size) * 255

        # add modified tile to sink
        # specify tile x, tile y, and any arbitrary frame parameters
        sink.addTile(processed_tile, x=tile['x'], y=tile['y'], footprint=i, footprint_value=footprint_size)
# view metadata
sink.getMetadata()
```

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

### Get Custom Thumbnail

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Retrieve a thumbnail with specified dimensions and encoding (e.g., PNG).

```python
import large_image
source = large_image.open('sample.tiff')
image, mime_type = source.getThumbnail(width=640, height=480, encoding='PNG')
open('thumb.png', 'wb').write(image)
```

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

### Style Parameter Documentation

Source: https://github.com/girder/large_image/blob/master/docs/tilesource_options.md

Detailed explanation of the 'style' parameter and its sub-options for customizing tile rendering.

```APIDOC
## Style Parameter

Often tiles are desired as 8-bit-per-sample images. However, if the tile source is more than 8 bits per sample or has more than 3 channels, some data will be lost. Similarly, if the data is returned as a numpy array, the range of values returned can vary by tile source. The `style` parameter can remap samples values and determine how channels are composited.

If `style` is `{{}}`, the default style for the file is used. If it is not specified or `None`, it will be the default style for non-geospatial tile sources and a default style consisting of the visible bands for geospatial sources. Otherwise, this is a JSON-encoded string that contains an object with a key of `bands` consisting of an array of band definitions. If only one band is needed, a JSON-encoded string of just the band definition can be used.

### Band Definition

A band definition is an object which can contain the following keys:

- **band** (integer | string) - Optional - If -1 or None, the greyscale value is used. Otherwise, a 1-based numerical index into the channels of the image or a string that matches the interpretation of the band (‘red’, ‘green’, ‘blue’, ‘gray’, ‘alpha’). Note that ‘gray’ on an RGB or RGBA image will use the green band.
- **frame** (integer) - Optional - If specified, override the frame parameter used in the tile query for this band. Note that it is more efficient to have at least one band not specify a frame parameter or use the same value as the basic query. Defaults to the frame value of the core query.
- **framedelta** (integer) - Optional - If specified, and `frame` is not specified, override the frame parameter used in the tile query for this band by adding the value to the current frame number. If many different frames are being requested, all with the same `framedelta`, this is more efficient than varying the `frame` within the style. Defaults to the frame value of the core query.
- **min** (number | string) - Optional - The value to map to the first palette value. Defaults to 0. Supported string values include:
    - `auto`: Use 0 if the reported minimum and maximum of the band are between [0, 255], otherwise use the reported minimum.
    - `min`: Always use the reported minimum.
    - `max`: Always use the reported maximum.
    - `min:<threshold>`: Pick a value that excludes a threshold amount from the histogram (e.g., `min:0.02` excludes at most the dimmest 2% of values).
    - `max:<threshold>`: Pick a value that excludes a threshold amount from the histogram (e.g., `max:0.02` excludes at most the brightest 2% of values).
    - `auto:<threshold>`: Works like `auto`, but applies the threshold if the reported minimum would otherwise be used.
    - `full`: Same as specifying 0.
- **max** (number | string) - Optional - The value to map to the last palette value. Defaults to 255. Supported string values include:
    - `auto`: Use 255 if the reported minimum and maximum of the band are between [0, 255], otherwise use the reported maximum.
    - `min`: Always use the reported minimum.
    - `max`: Always use the reported maximum.
    - `min:<threshold>`: Pick a value that excludes a threshold amount from the histogram.
    - `max:<threshold>`: Pick a value that excludes a threshold amount from the histogram.
    - `auto:<threshold>`: Works like `auto`, but applies the threshold if the reported maximum would otherwise be used.
    - `full`: Uses a value based on the data type of the band (1 for float, 255 for uint8, 65535 for uint16).
- **palette** (string | array) - Optional - This is a single color string, a palette name, or a list of two or more colors. The values between min and max are interpolated using a piecewise linear algorithm or a nearest value algorithm (depending on the `scheme`) to map to the specified palette values. It can be specified in a variety of ways:
    - A list of two or more color values (CSS-style strings like `#RRGGBB`, `#RRGGBBAA`, `#RGB`, `#RGBA`, `rgb()`, `rgba()`, `hsl()`, `hsv()`, CSS color names, matplotlib color names, or lists/tuples of RGB(A) values [0-1]).
    - A single string that is a color string as above (functionally a two-color palette with black as the first color).
    - A named color palette from the `palettable` or `matplotlib` libraries (e.g., `matplotlib.Plasma_6`, `viridis`).
- **scheme** (string) - Optional - Either `linear` (default) or `discrete`. If a palette is specified, `linear` uses piecewise linear interpolation, and `discrete` uses exact colors from the palette.
- **nodata** (any) - Optional - The value to use for missing data. `null` or unset to not use a nodata value.
- **composite** (string) - Optional - Either `lighten` or `multiply`. Defaults to `lighten` for all except the alpha band. Read more about blend modes and see examples [here](https://developer.mozilla.org/en-US/docs/Web/CSS/blend-mode).
```

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

### Pixelmap Values Array

Source: https://github.com/girder/large_image/blob/master/girder_annotation/docs/annotations.rst

An example of a values array used for mapping pixelmap indices to categories.

```json
    "values": [
      0.508,
      0.806,
      0.311,
      0.402,
      0.535,
      0.661,
      0.866,
      0.31,
      0.241,
      0.63,
      0.555,
      0.067,
      0.668,
      0.164,
      0.512,
      0.647,
      0.501,
      0.637,
      0.498,
      0.658,
      0.332,
      0.431,
      0.053,
      0.531
    ]
  }
```

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

### Nested Key-Value Data Arrangement

Source: https://github.com/girder/large_image/blob/master/docs/plottable.md

Example of a 'meta' dictionary with nested keys for plottable data.

```default
"meta": {
  "nucleus": {
    "radius": 4.5,
    "circularity": 0.9
  }
}
```

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

### Download sample data

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/zarr_sink_example.ipynb

Retrieve a sample TIFF file for processing.

```python
!curl -L -C - -o example.tiff https://demo.kitware.com/histomicstk/api/v1/item/58b480ba92ca9a000b08c899/download
```

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

### Open and inspect image source

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/zarr_sink_example.ipynb

Load an image file and retrieve its metadata.

```python
original_image_path = 'example.tiff'
processed_image_path = 'processed_example_1.tiff'

source = large_image.open(original_image_path)

# view the metadata
source_metadata = source.getMetadata()
source_metadata
```

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

### Get Default Thumbnail

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Retrieve a default-sized thumbnail (typically JPEG, max 256x256) of the entire image.

```python
import large_image
source = large_image.open('sample.tiff')
image, mime_type = source.getThumbnail()
open('thumb.jpg', 'wb').write(image)
```

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

### Clone Repository

Source: https://github.com/girder/large_image/blob/master/docs/development.md

Initial steps to clone the large_image repository from GitHub.

```default
git clone https://github.com/girder/large_image.git
cd large_image
```

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

### List Associated Images

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Get a list of available associated images (e.g., 'label', 'macro') within a large image.

```python
import large_image
source = large_image.open('sample.tiff')
print(source.getAssociatedImagesList())
# This prints something like:
#   ['label', 'macro']
```

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

### Download sample image file

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/frame_viewer_example.ipynb

Retrieve a sample TIFF file for demonstration purposes using curl.

```python
# Get a file so we can use it locally
!curl -L -C - -o wd-extract.jpeg.tiff https://data.kitware.com/api/v1/file/hashsum/sha512/ab0e68399f924484b96e2268e3ac277875b10619a673dcf3951380a5e5f0c9bb2b37139a8c522dacc0f40036fcb438a30143b69874454299af64ebb8062b272a/download
```

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

### Get Associated Image

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Retrieve a specific associated image. Supports different encodings and formats, returning the entire image data.

```python
import large_image
source = large_image.open('sample.tiff')
image, mime_type = source.getAssociatedImage('macro')
# image is a binary image, such as a JPEG
image, mime_type = source.getAssociatedImage('macro', encoding='PNG')
# image is now a PNG
image, mime_type = source.getAssociatedImage('macro', format=large_image.constants.TILE_FORMAT_NUMPY)
# image is now a numpy array
```

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

### Nested Key-Value List Data Arrangement

Source: https://github.com/girder/large_image/blob/master/docs/plottable.md

Example of a 'meta' dictionary with nested keys mapping to lists of values for plottable data.

```default
"meta": {
  "nucleus": {
    "radius": [4.5, 5.5, 5.1],
    "circularity": [0.9, 0.86, 0.92]
  }
}
```

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

### Get Region with Corner and Distances

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Extract a region from a geospatial image by specifying a corner point and distances for width and height. The units for width and height can be specified separately.

```python
import large_image
source = large_image.open('geo_sample.tiff')
if source.geospatial:
    nparray, mime_type = source.getRegion(
        region=dict(
            top=42.3008, left=-71.1143, units='EPSG:4326',
            width=3, height=4, unitsWH='km'
        ),
        format=large_image.constants.TILE_FORMAT_NUMPY
    )
```

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

### Initialize Map with ID or Resource Path

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/large_image_examples.ipynb

Create a map visualization by providing either a Girder item ID or a resource path to the large_image Jupyter Map constructor.

```python
map1 = large_image.tilesource.jupyter.Map(gc=gc1, id='57b345d28d777f126827dc28')
map1
```

```python
map2 = large_image.tilesource.jupyter.Map(gc=gc1, resource='/collection/HistomicsTK/CI and tox Test Data/large_image test files/Huron.Image2_JPEG2K.tif')
map2
```

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

### Download sample image files

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/large_image_examples.ipynb

Downloads two sample image files, a GeoTIFF COG and a SVS file, using curl for local use with the large_image library. The `-L` flag follows redirects, `-C -` resumes interrupted downloads, and `-o` specifies the output filename.

```bash
# Get a few files so we can use them locally
!curl -L -C - -o TC_NG_SFBay_US_Geo_COG.tif https://data.kitware.com/api/v1/file/hashsum/sha512/5e56cdb8fb1a02615698a153862c10d5292b1ad42836a6e8bce5627e93a387dc0d3c9b6cfbd539796500bc2d3e23eafd07550f8c214e9348880bbbc6b3b0ea0c/download
!curl -L -C - -o TCGA-AA-A02O-11A-01-BS1.svs https://data.kitware.com/api/v1/file/hashsum/sha512/1b75a4ec911017aef5c885760a3c6575dacf5f8efb59fb0e011108dce85b1f4e97b8d358f3363c1f5ea6f1c3698f037554aec1620bbdd4cac54e3d5c9c1da1fd/download
```

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

### Get Image Region as NumPy Array

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Retrieves a specific region of an image as a NumPy array for the middle channel. Ensure the large_image library is imported and the source image is opened.

```python
nparray, mime_type = source.getRegion(
    frame=1,
    format=large_image.constants.TILE_FORMAT_NUMPY)
# nparray will contain data from the middle channel image
```

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

### Configure Jupyter proxy

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/zarr_sink_example.ipynb

Set up the Jupyter proxy for the tile server, handling specific requirements for Google Colab environments.

```python
import importlib.util
import large_image

if importlib.util.find_spec('google') and importlib.util.find_spec('google.colab'):
    # colab intercepts localhost
    large_image.tilesource.jupyter.IPyLeafletMixin.JUPYTER_PROXY = 'https://localhost'
else:
    large_image.tilesource.jupyter.IPyLeafletMixin.JUPYTER_PROXY = True
```

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

### Get Region with Projection Coordinates

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Extract a region from a geospatial image using projection coordinates (e.g., latitude and longitude). Ensure the image is opened and checked for geospatial capabilities before calling.

```python
import large_image
source = large_image.open('geo_sample.tiff')
if source.geospatial:
    nparray, mime_type = source.getRegion(
        region=dict(
            top=42.3008, bottom=42.3006,
            left=-71.1143, right=-71.1140,
            units='EPSG:4326'
        ),
        format=large_image.constants.TILE_FORMAT_NUMPY
    )
```

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

### Load image and retrieve thumbnail

Source: https://github.com/girder/large_image/blob/master/docs/notebooks/frame_viewer_example.ipynb

Open a large image file to read metadata and generate a thumbnail.

```python
import large_image

source = large_image.open('wd-extract.jpeg.tiff')
# The thumbnail method returns a tuple with an image or numpy array and a mime type
source.getThumbnail()[0]
```

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

### Get Image Region as PNG

Source: https://github.com/girder/large_image/blob/master/docs/getting_started.md

Extracts a specified region of an image at a given resolution and returns it as a PNG encoded byte string. The output size can be constrained using maxWidth or maxHeight.

```python
import large_image
source = large_image.open('sample.tiff')
image, mime_type = source.getRegion(
    region=dict(left=1000, top=500, right=11000, bottom=1500),
    output=dict(maxWidth=1000),
    encoding='PNG')
```

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

### Multi Z-position with Path Pattern

Source: https://github.com/girder/large_image/blob/master/sources/multi/docs/specification.rst

This configuration simplifies specifying multiple z-slices by using a 'pathPattern' to match files and 'zStep' to define the increment between z-values. Files are sorted lexicographically.

```yaml
---
sources:
  - path: .
    pathPattern: 'test_orient[1-8]\.tif'
    zStep: 1
```

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

### Define Multi-Source via Path Pattern

Source: https://github.com/girder/large_image/blob/master/docs/multi_source_specification.md

Use regular expressions to match multiple files and assign Z-values automatically.

```yaml
---
sources:
  - path: .
    pathPattern: 'test_orient[1-8]\.tif'
    zStep: 1
```

```yaml
---
sources:
  - path: .
    pathPattern: 'test_orient(?P<z1>[1-8])\.tif'
```