Large Image

The Tile Source Cache optimizes the reading of specific large images by storing file handles, parsed metadata, and other values.

Key Characteristics:

• Storage: Always stored in the Python process memory and is not shared between processes.
• Cache Keys: The key includes the tile source, default tile format, and style.
• Resource Sharing: File handles and metadata are shared across sources that only differ in style (e.g., if one request applies ICC color correction and another does not).
• Memory Management: Memory usage varies significantly by tile source. The system estimates usage based on sample files and calculates the maximum number of sources to cache based on a fraction of total memory reported by psutils.
• Implementation Note for Developers: Because file handles are shared across sources that only differ in style, if you implement a custom __del__ operator in a source, it must check if it is the unstyled source before performing cleanup.

YAML configuration files support hierarchical settings and access control based on user roles and group membership.

Key structural elements:

• Base level: Standard key-value pairs.
• access: Defines settings for specific user roles:
  • user: Settings applied to logged-in users.
  • admin: Settings applied to admin users.
  • Note: If a dictionary key matches a base-level key, values are merged. Use __all__: true to completely replace the base value.
• groups: Specifies settings for specific user groups.
• users: Specifies settings for specific user logins.
• __inherit__: A boolean that, if true, merges this file with its parent's configuration.

---
# Base settings
key: value

access:
  user:
    key: value
  admin:
    key: value

groups:
  group_name:
    key: value
    access:
      user: ...

users:
  user_login:
    key: value

__inherit__: true
---

When the GET /item/{id}/tile/zxy/{z}/{x}/{y}?style=<style>&encoding=<encoding>&... endpoint is called, Girder follows a hierarchical lookup and synthesis process:

1. Tile Cache Check: It first checks if the specific requested tile is already in the tile cache.
2. Source Cache Check: If not in the tile cache, it checks if the file-like object (the source) is in the source cache with the requested style and encoding.
3. Unstyled Source Handling: If the styled source isn't cached, it looks for an unstyled version with the requested encoding. If missing, it opens the unstyled file, caches it, and then creates/caches the styled version.
4. Tile Synthesis/Extraction:
   • If the unstyled tile is not in the cache, Girder either reads it directly from the file or synthesizes it from higher-resolution tiles.
   • The resulting unstyled tile is then placed in the tile cache.
5. Styling and Encoding:
   • If a style is required, Girder converts the tile (to a numpy array if necessary) and generates the styled version.
   • The tile is then encoded to the requested encoding format.
   • The final encoded tile is placed in the tile cache and served.

graph TD;
    apicall(["GET /item/{id}/tile/zxy/{z}/{x}/{y}?style=<style>&encoding=<encoding>&..."])
    checktile1{Is tile in\ntile cache?}
    apicall --> checktile1;
    getfile[("Get file-like object\nor url from Girder")]
    checktile1 -- No --> getfile;
    servetile(["Serve tile 🖼️"])
    checktile1 -- Yes --> servetile;
    checksource{"Is file-like object\nin source cache\nwith {style}\nand {encoding}?"}
    getfile --> checksource;
    checkunstyled{"Is unstyled file\nin source cache\nwith {encoding}?"}
    checksource -- No --> checkunstyled;
    openunstyle["Open unstyled file with {encoding}"]
    checkunstyled -- No --> openunstyle;
    putunstyledsource["/Put unstyled source in cache"/]
    openunstyle --> putunstyledsource;
    alter["Copy unstyled source\nand alter for {style}"]
    putunstyledsource --> alter;
    checkunstyled -- Yes --> alter;
    putsource["/Put styled source in cache"/]
    alter --> putsource;
    checktile2{"Is unstyled tile\n{x}, {y}, {z},\n{frame}, {encoding}\nin tile cache?"}
    putsource --> checktile2;
    checksource -- Yes --> checktile2;
    checktile3{"Does tile exist\nin the file?"}
    checktile2 -- No --> checktile3;
    maketile[["Synthesize tile\nfrom higher\nresolution tiles"]]
    checktile3 -- No --> maketile;
    readfile[("Read tile from file")]
    checktile3 -- Yes --> readfile;
    puttile1["/Put unstyled\ntile in cache"/]
    maketile --> puttile1;
    readfile --> puttile1;
    gettile["Read unstyled tile\nfrom cache"]
    checktile2 -- Yes --> gettile;
    needstyle{"Is {style}\nrequired?"}
    puttile1 --> needstyle;
    gettile --> needstyle;
    checkencoding{"Is tile\nin {encoding}?"}
    needstyle -- No --> checkencoding;
    isnumpy{"Is unstyled\ntile a\nnumpy array?"}
    needstyle -- Yes --> isnumpy;
    makenumpy["Convert tile to numpy"]
    isnumpy -- No --> makenumpy;
    makestyle["Generate styled tile in numpy format\n(Note that this could fetch other tiles)"]
    isnumpy -- Yes --> makestyle;
    makenumpy --> makestyle;
    makestyle --> checkencoding;
    encode["Encode tile to {encoding}"]
    checkencoding -- No --> encode;
    puttile2["/Put encoded tile\nin cache"/]
    encode --> puttile2;
    checkencoding -- Yes --> puttile2;
    puttile2 --> servetile;

The Tile Cache stores individual images or numpy arrays for each processed tile. This allows for rapid retrieval of previously computed tiles.

Key Characteristics:

• Storage Backends: Can be stored in the Python process memory or in memcached. Custom cache backends can also be added.
• Cache Keys: The key is a hash derived from the tile source, tile location within the source, format, compression, and style.
• Sharing: Using memcached allows cached tiles to be shared across multiple processes. In-process memory caching is local to the specific Python process.
• Content: Cached tiles can include original as-read data, styled data, or transformed data. It also caches synthesized tiles for sources missing specific resolutions.
• Memory Management:
  • memcached: Memory usage and location are determined by the memcached configuration. Note that memcached may need configuration to allow the larger values required by tiles.
  • Python Process: Memory is limited to a fraction of the total system memory as reported by psutils.