Calino User Manual

Book Metadata

CREATOR | Mark Raynsford
DATE | 2022-04-30T09:40:19+00:00
DESCRIPTION | Documentation for Calino tools and APIs.
IDENTIFIER | 5a095a15-61f0-4eea-954f-05932ec3e4b5
LANGUAGE | en
RIGHTS | Public Domain
TITLE | Calino User Manual

Table Of Contents

Cover

Colophon

Table Of Contents

1. Command-Line Interface

1.1. Overview

1.2. check

1.2.1. Name

1.2.2. Description

1.2.3. Examples

1.3. create-2d

1.3.1. Name

1.3.2. Description

1.3.3. Examples

1.4. create-array

1.4.1. Name

1.4.2. Description

1.4.3. Examples

1.5. create-cube

1.5.1. Name

1.5.2. Description

1.5.3. Examples

1.6. extract-image-data-2d

1.6.1. Name

1.6.2. Description

1.6.3. Examples

1.7. extract-image-data-array

1.7.1. Name

1.7.2. Description

1.7.3. Examples

1.8. extract-image-data-cube

1.8.1. Name

1.8.2. Description

1.8.3. Examples

1.9. show-image-info

1.9.1. Name

1.9.2. Description

1.9.3. Examples

1.10. show-metadata

1.10.1. Name

1.10.2. Description

1.10.3. Examples

1.11. show-sections

1.11.1. Name

1.11.2. Description

1.11.3. Examples

1.12. show-summary

1.12.1. Name

1.12.2. Description

1.12.3. Examples

1.13. show-version

1.13.1. Name

1.13.2. Description

1.13.3. Examples

1.14. version

1.14.1. Name

1.14.2. Description

1.14.3. Examples

2. API

1. Command-Line Interface

1.1. Overview

1.2. check

1.2.1. Name

1.2.2. Description

1.2.3. Examples

1.3. create-2d

1.3.1. Name

1.3.2. Description

1.3.3. Examples

1.4. create-array

1.4.1. Name

1.4.2. Description

1.4.3. Examples

1.5. create-cube

1.5.1. Name

1.5.2. Description

1.5.3. Examples

1.6. extract-image-data-2d

1.6.1. Name

1.6.2. Description

1.6.3. Examples

1.7. extract-image-data-array

1.7.1. Name

1.7.2. Description

1.7.3. Examples

1.8. extract-image-data-cube

1.8.1. Name

1.8.2. Description

1.8.3. Examples

1.9. show-image-info

1.9.1. Name

1.9.2. Description

1.9.3. Examples

1.10. show-metadata

1.10.1. Name

1.10.2. Description

1.10.3. Examples

1.11. show-sections

1.11.1. Name

1.11.2. Description

1.11.3. Examples

1.12. show-summary

1.12.1. Name

1.12.2. Description

1.12.3. Examples

1.13. show-version

1.13.1. Name

1.13.2. Description

1.13.3. Examples

1.14. version

1.14.1. Name

1.14.2. Description

1.14.3. Examples

1.1. Overview

The calino package provides a command-line interface for performing tasks such as creating textures, validating textures, and extracting texture data to various file formats. The base calino command is broken into a number of subcommands which are documented over the following sections.

1.1.2. Command-Line Overview

calino: INFO: Usage: calino [options] [command] [command options]

  Options:
    --verbose
      Set the minimum logging verbosity level.
      Default: info
      Possible Values: [trace, debug, info, warn, error]

  Use the "help" command to examine specific commands:

    $ calino help help.

  Command-line arguments can be placed one per line into a file, and the file
  can be referenced using the @ symbol:

    $ echo help > file.txt
    $ echo help >> file.txt
    $ calino @file.txt

  Commands:
    check                        Check a texture file.
    create-2d                    Create a 2D texture from an existing image.
    create-array                 Create an array texture from an existing image.
    create-cube                  Create a cube texture from existing images.
    extract-image-data-2d        Extract 2D image data from a file
    extract-image-data-array     Extract array image data from a file
    extract-image-data-cube      Extract cube image data from a file
    help                         Show detailed help messages for commands.
    show-image-info              Display texture file image info.
    show-metadata                Display texture file metadata.
    show-sections                List sections in a texture file
    show-summary                 Display information about texture files.
    show-version                 Display texture file version.
    version                      Display the application version.

  Documentation:
    https://www.io7m.com/software/calino/documentation/index.xhtml

All of the command-line functionality is implemented using the standard calino APIs. Applications wishing to do more advanced image processing should use those APIs directly.

1.2. check

1.2.1. Name

1.2.2. Description

1.2.3. Examples

1.2.1. Name

check - Validate texture files

1.2.2. Description

The check command validates texture files.

1.2.2.2. Parameters

Parameter | Type | Required | Description
--file | Path | true | The texture file
--warnings-as-errors | boolean | false | Treat validation warnings as errors
--format-version | CLNVersion | false | The requested file format version
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The check command will read the texture file specified with --file and perform extensive validity testing against the properties given in the calino specification. Additionally, it will extract all image data into memory and check the data against any CRC32 checksums included in the texture file.

If the command encounteres no validation errors or warnings, it will not print anything.

1.2.3. Examples

1.2.3.1. Example

$ calino check --file validation-cube-crc-mismatch.ctf
calino: ERROR: validation-cube-crc-mismatch.ctf: @0x310: The mipmap description for layer 2, face X_NEGATIVE specifies a CRC32 value of 0x5edf2461 but the actual data had a CRC32 of 0x5edf2460.
calino: ERROR:   See https://www.io7m.com/software/calino/specification/index.xhtml#id_09645697-fbde-43fe-9f34-48c851adb2ff for details.
$ echo $?
1

$ calino check --file validation-cube-size-mismatch.ctf
calino: ERROR: validation-cube-size-mismatch.ctf: @0x2f0: The mipmap description for layer 2, face X_POSITIVE specifies that the mipmap data should be 12 octets uncompressed, but the actual data was 13 octets.
calino: ERROR:   See https://www.io7m.com/software/calino/specification/index.xhtml#id_e676eaef-f25a-44e8-9360-bcfaf35ce1e6 for details.
calino: WARN: validation-cube-size-mismatch.ctf: @0xe0: For uncompressed image data, the compressed size 13 must equal the uncompressed size 12 (at level 2).
calino: WARN:   See https://www.io7m.com/software/calino/specification/index.xhtml#id_579b15a3-09bb-4b14-87ab-0441ecc88b31 for details.
$ echo $?
1

$ calino check --file array-mips.ctf
$ echo $?
0

1.3. create-2d

1.3.1. Name

1.3.2. Description

1.3.3. Examples

1.3.1. Name

create-2d - Create 2D textures

1.3.2. Description

The create-2d command creates 2D texture files.

1.3.2.2. Parameters

Parameter | Type | Required | Description
--source | Path | true | The source image file
--output | Path | true | The output texture file
--mipmap-generate | CLNImageMipMapFilter | false | The mipmap filter
--premultiply-alpha | boolean | false | Premultiply alpha
--byte-order | CLNByteOrder | false | The byte order used for image data
--format-version | CLNVersion | false | The requested file format version
--convert-layout-to | CLNChannelsLayoutDescriptionType | false | The requested layout to which to convert
--super-compression | CLNSuperCompressionMethodType | false | The super compression method.
--metadata | Path | false | A Java properties file containing metadata for the texture file.
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command takes an image file specified with --file and writes a texture file to --output.

If the --mipmap-generate parameter is specified with a value of one of the named filters [BICUBIC, BILINEAR, NEAREST] then a series of mipmaps will be generated in the texture file with each scaled-down mip level being processed with the given filter.

If the --byte-order parameter is specified with a value of one of the named endianness values [BIG_ENDIAN, LITTLE_ENDIAN]. The endianness value determines how image data will be stored and is primarily useful for applications that wish to memory-map texture files for direct uploading to GPUs.

The --convert-layout-to parameter specifies that the image data provided by the input file should be converted to the given channel layout.

The --metadata parameter specifies a file containing key/value metadata in Java properties format. The metadata keys and values will be inserted into the generated texture file.

If the --premultiply-alpha parameter is specified, then the data in the input file will be alpha-premultiplied when written to the output texture file.

If the --super-compression parameter is specified, then the image data in the output file will be compressed using the given compression method. Currently, the only supported supercompression method is LZ4.

1.3.3. Examples

1.3.3.1. Example

$ calino create-2d \
--mipmap-generate BILINEAR \
--output output.ctf \
--super-compression LZ4 \
--premultiply-alpha true \
--metadata input.properties \
--convert-layout-to "p16|R4:G4:B4:A4" \
--source input.png

1.4. create-array

1.4.1. Name

1.4.2. Description

1.4.3. Examples

1.4.1. Name

create-array - Create array textures

1.4.2. Description

The create-array command creates array texture files.

1.4.2.2. Parameters

Parameter | Type | Required | Description
--source-layer | List | true | The source image layer files, in layer order starting at 0
--output | Path | true | The output texture file
--mipmap-generate | CLNImageMipMapFilter | false | The mipmap filter
--premultiply-alpha | boolean | false | Premultiply alpha
--byte-order | CLNByteOrder | false | The byte order used for image data
--format-version | CLNVersion | false | The requested file format version
--convert-layout-to | CLNChannelsLayoutDescriptionType | false | The requested layout to which to convert
--super-compression | CLNSuperCompressionMethodType | false | The super compression method.
--metadata | Path | false | A Java properties file containing metadata for the texture file.
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command takes a series of image files specified with repeated instances of --source-layer, and writes a texture file to --output. The layers of the resulting array image will match the order in which --source-layer parameters were specified, with the first instance of --source-layer defining layer 0, and the nth instance of --source-layer defining layer n-1.

If the --mipmap-generate parameter is specified with a value of one of the named filters [BICUBIC, BILINEAR, NEAREST] then a series of mipmaps will be generated in the texture file with each scaled-down mip level being processed with the given filter.

If the --byte-order parameter is specified with a value of one of the named endianness values [BIG_ENDIAN, LITTLE_ENDIAN]. The endianness value determines how image data will be stored and is primarily useful for applications that wish to memory-map texture files for direct uploading to GPUs.

The --convert-layout-to parameter specifies that the image data provided by the input file should be converted to the given channel layout.

The --metadata parameter specifies a file containing key/value metadata in Java properties format. The metadata keys and values will be inserted into the generated texture file.

If the --premultiply-alpha parameter is specified, then the data in the input file will be alpha-premultiplied when written to the output texture file.

If the --super-compression parameter is specified, then the image data in the output file will be compressed using the given compression method. Currently, the only supported supercompression method is LZ4.

1.4.3. Examples

1.4.3.1. Example

$ calino create-array \
--mipmap-generate BILINEAR \
--output output.ctf \
--super-compression LZ4 \
--metadata input.properties \
--convert-layout-to "R8:G8:B8:A8" \
--source-layer layer0.png \
--source-layer layer1.png \
--source-layer layer2.png \
--source-layer layer3.png \
--source-layer layer4.png \
--source-layer layer5.png \
--source-layer layer6.png \
--source-layer layer7.png

1.5. create-cube

1.5.1. Name

1.5.2. Description

1.5.3. Examples

1.5.1. Name

create-cube - Create cube textures

1.5.2. Description

The create-cube command creates cube texture files.

1.5.2.2. Parameters

Parameter | Type | Required | Description
--source-x-positive | Path | true | The source image file for the positive X face
--source-x-negative | Path | true | The source image file for the negative X face
--source-y-positive | Path | true | The source image file for the positive Y face
--source-y-negative | Path | true | The source image file for the negative Y face
--source-z-positive | Path | true | The source image file for the positive Z face
--source-z-negative | Path | true | The source image file for the negative Z face
--output | Path | true | The output texture file
--mipmap-generate | CLNImageMipMapFilter | false | The mipmap filter
--premultiply-alpha | boolean | false | Premultiply alpha
--byte-order | CLNByteOrder | false | The byte order used for image data
--format-version | CLNVersion | false | The requested file format version
--convert-layout-to | CLNChannelsLayoutDescriptionType | false | The requested layout to which to convert
--super-compression | CLNSuperCompressionMethodType | false | The super compression method.
--metadata | Path | false | A Java properties file containing metadata for the texture file.
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command takes a set of image files specified with --source-x-negative, --source-x-positive, --source-y-negative, --source-y-positive, --source-z-negative, and --source-z-positive, and writes a texture file to --output.

If the --mipmap-generate parameter is specified with a value of one of the named filters [BICUBIC, BILINEAR, NEAREST] then a series of mipmaps will be generated in the texture file with each scaled-down mip level being processed with the given filter.

If the --byte-order parameter is specified with a value of one of the named endianness values [BIG_ENDIAN, LITTLE_ENDIAN]. The endianness value determines how image data will be stored and is primarily useful for applications that wish to memory-map texture files for direct uploading to GPUs.

The --convert-layout-to parameter specifies that the image data provided by the input file should be converted to the given channel layout.

The --metadata parameter specifies a file containing key/value metadata in Java properties format. The metadata keys and values will be inserted into the generated texture file.

If the --premultiply-alpha parameter is specified, then the data in the input file will be alpha-premultiplied when written to the output texture file.

If the --super-compression parameter is specified, then the image data in the output file will be compressed using the given compression method. Currently, the only supported supercompression method is LZ4.

1.5.3. Examples

1.5.3.1. Example

$ calino create-cube \
--mipmap-generate BILINEAR \
--output output.ctf \
--super-compression LZ4 \
--metadata input.properties \
--convert-layout-to "p16|R5:G6:B5" \
--source-x-negative x-n-input.png \
--source-x-positive x-p-input.png \
--source-y-negative y-n-input.png \
--source-y-positive y-p-input.png \
--source-z-negative z-n-input.png \
--source-z-positive z-p-input.png

1.6. extract-image-data-2d

1.6.1. Name

1.6.2. Description

1.6.3. Examples

1.6.1. Name

extract-image-data-2d - Extract image data from 2D textures.

1.6.2. Description

The extract-image-data-2d command extracts image data from 2D texture files.

1.6.2.2. Parameters

Parameter | Type | Required | Description
--output-directory | Path | true | The output directory
--decompress | boolean | false | Whether to decompress data during extraction (ignored if the output is PNG).
--output-format | CLNOutputFormat | false | The output format
--file | Path | true | The texture file
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command extracts all mipmaps available in the source texture to the output directory specified with --output-directory. If source texture's mipmaps are compressed with supercompression (such as LZ4), then the mipmaps can be optionally decompressed with --decompress.

The output format can be specified with --output-format which may be one of [RAW, PNG]. If the output format is RAW, then the raw bytes that make up image data will be written to the output files directly with no header or other information. If --decompress is not specified, then the raw bytes will be those of the compressed data. If the output format is PNG, then the image data will be written to the output files in PNG format. Note that this will necessarily and automatically decompress the image data, and may also downsample the image data because PNG does not support as wide a range of image data layouts as calino texture files.

For a given output directory D, the command will write each of the mipmap levels of the input image to files in D. The name of each output file will be "m", followed by a zero-padded level number, followed by an appropriate file suffix such as ".png" or ".raw".

1.6.3. Examples

1.6.3.1. Example

$ calino extract-image-data-2d \
--file example-ctf \
--output-directory /tmp/out \
--output-format PNG
calino: INFO: writing level 7 to /tmp/out/m007.png
calino: INFO: writing level 6 to /tmp/out/m006.png
calino: INFO: writing level 5 to /tmp/out/m005.png
calino: INFO: writing level 4 to /tmp/out/m004.png
calino: INFO: writing level 3 to /tmp/out/m003.png
calino: INFO: writing level 2 to /tmp/out/m002.png
calino: INFO: writing level 1 to /tmp/out/m001.png
calino: INFO: writing level 0 to /tmp/out/m000.png

1.7. extract-image-data-array

1.7.1. Name

1.7.2. Description

1.7.3. Examples

1.7.1. Name

extract-image-data-array - Extract image data from array textures.

1.7.2. Description

The extract-image-data-array command extracts image data from array texture files.

1.7.2.2. Parameters

Parameter | Type | Required | Description
--file | Path | true | The texture file
--output-directory | Path | true | The output directory
--decompress | boolean | false | Whether to decompress data during extraction (ignored if the output is PNG).
--output-format | CLNOutputFormat | false | The output format
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command extracts all mipmaps available in the source texture to the output directory specified with --output-directory. If source texture's mipmaps are compressed with supercompression (such as LZ4), then the mipmaps can be optionally decompressed with --decompress.

The output format can be specified with --output-format which may be one of [RAW, PNG]. If the output format is RAW, then the raw bytes that make up image data will be written to the output files directly with no header or other information. If --decompress is not specified, then the raw bytes will be those of the compressed data. If the output format is PNG, then the image data will be written to the output files in PNG format. Note that this will necessarily and automatically decompress the image data, and may also downsample the image data because PNG does not support as wide a range of image data layouts as calino texture files.

For a given output directory D, the command will write each of the mipmap levels of the input image to files in D. The name of each output file will be "m", followed by a zero-padded level number, followed by "v", followed by a zero-padded layer number, followed by an appropriate file suffix such as ".png" or ".raw".

1.7.3. Examples

1.7.3.1. Example

$ calino extract-image-data-array
--file example-ctf \
--output-directory /tmp/out \
--output-format PNG
calino: INFO: writing level 3 to /tmp/out/m003v000.png
calino: INFO: writing level 3 to /tmp/out/m003v001.png
calino: INFO: writing level 3 to /tmp/out/m003v002.png
calino: INFO: writing level 2 to /tmp/out/m002v000.png
calino: INFO: writing level 2 to /tmp/out/m002v001.png
calino: INFO: writing level 2 to /tmp/out/m002v002.png
calino: INFO: writing level 1 to /tmp/out/m001v000.png
calino: INFO: writing level 1 to /tmp/out/m001v001.png
calino: INFO: writing level 1 to /tmp/out/m001v002.png
calino: INFO: writing level 0 to /tmp/out/m000v000.png
calino: INFO: writing level 0 to /tmp/out/m000v001.png
calino: INFO: writing level 0 to /tmp/out/m000v002.png

1.8. extract-image-data-cube

1.8.1. Name

1.8.2. Description

1.8.3. Examples

1.8.1. Name

extract-image-data-cube - Extract image data from cube textures.

1.8.2. Description

The extract-image-data-cube command extracts image data from cube texture files.

1.8.2.2. Parameters

Parameter | Type | Required | Description
--file | Path | true | The texture file
--output-directory | Path | true | The output directory
--decompress | boolean | false | Whether to decompress data during extraction (ignored if the output is PNG).
--output-format | CLNOutputFormat | false | The output format
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command extracts all mipmaps available in the source texture to the output directory specified with --output-directory. If source texture's mipmaps are compressed with supercompression (such as LZ4), then the mipmaps can be optionally decompressed with --decompress.

The output format can be specified with --output-format which may be one of [RAW, PNG]. If the output format is RAW, then the raw bytes that make up image data will be written to the output files directly with no header or other information. If --decompress is not specified, then the raw bytes will be those of the compressed data. If the output format is PNG, then the image data will be written to the output files in PNG format. Note that this will necessarily and automatically decompress the image data, and may also downsample the image data because PNG does not support as wide a range of image data layouts as calino texture files.

For a given output directory D, the command will write each of the mipmap levels of the input image to files in D. The name of each output file will be "m", followed by a zero-padded level number, followed by "f", followed by a face name, followed by an appropriate file suffix such as ".png" or ".raw".

A face name is one of the following:

1.8.2.7. Face Names

xp for the positive X face.

xn for the negative X face.

yp for the positive Y face.

yn for the negative Y face.

zp for the positive Z face.

zn for the negative Z face.

1.8.3. Examples

1.8.3.1. Example

$ calino extract-image-data-cube
--file example-ctf \
--output-directory /tmp/out \
--output-format PNG
calino: INFO: writing level 3 to /tmp/out/m003fxp.png
calino: INFO: writing level 3 to /tmp/out/m003fxn.png
calino: INFO: writing level 3 to /tmp/out/m003fyp.png
calino: INFO: writing level 3 to /tmp/out/m003fyn.png
calino: INFO: writing level 3 to /tmp/out/m003fzp.png
calino: INFO: writing level 3 to /tmp/out/m003fzn.png
calino: INFO: writing level 2 to /tmp/out/m002fxp.png
calino: INFO: writing level 2 to /tmp/out/m002fxn.png
calino: INFO: writing level 2 to /tmp/out/m002fyp.png
calino: INFO: writing level 2 to /tmp/out/m002fyn.png
calino: INFO: writing level 2 to /tmp/out/m002fzp.png
calino: INFO: writing level 2 to /tmp/out/m002fzn.png
calino: INFO: writing level 1 to /tmp/out/m001fxp.png
calino: INFO: writing level 1 to /tmp/out/m001fxn.png
calino: INFO: writing level 1 to /tmp/out/m001fyp.png
calino: INFO: writing level 1 to /tmp/out/m001fyn.png
calino: INFO: writing level 1 to /tmp/out/m001fzp.png
calino: INFO: writing level 1 to /tmp/out/m001fzn.png
calino: INFO: writing level 0 to /tmp/out/m000fxp.png
calino: INFO: writing level 0 to /tmp/out/m000fxn.png
calino: INFO: writing level 0 to /tmp/out/m000fyp.png
calino: INFO: writing level 0 to /tmp/out/m000fyn.png
calino: INFO: writing level 0 to /tmp/out/m000fzp.png
calino: INFO: writing level 0 to /tmp/out/m000fzn.png

1.9. show-image-info

1.9.1. Name

1.9.2. Description

1.9.3. Examples

1.9.1. Name

show-image-info - Show image information in texture files.

1.9.2. Description

The show-image-info command displays the image information section in texture files.

1.9.2.2. Parameters

Parameter | Type | Required | Description
--file | Path | true | The texture file
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command displays the contents of the image info section directly, and does not validate that the texture file actually contains image data of the declared type.

1.9.3. Examples

1.9.3.1. Example

$ calino show-image-info --file array-mips.ctf
{
  "SizeX" : 256,
  "SizeY" : 256,
  "SizeZ" : 1,
  "Size" : "256×256×1",
  "ChannelLayout" : "R8:G8:B8:A8",
  "ChannelType" : "FIXED_POINT_NORMALIZED_UNSIGNED",
  "ColorSpace" : "SRGB",
  "Flags" : [ "ALPHA_PREMULTIPLIED" ],
  "CoordinateSystemR" : "RT",
  "CoordinateSystemS" : "SR",
  "CoordinateSystemT" : "TD",
  "CoordinateSystem" : "RT:SR:TD",
  "Compression" : "UNCOMPRESSED",
  "SuperCompression" : "DEFLATE",
  "TexelBlockAlignment" : 32
}

1.10. show-metadata

1.10.1. Name

1.10.2. Description

1.10.3. Examples

1.10.1. Name

show-metadata - Show metadata in texture files.

1.10.2. Description

The show-metadata command displays metadata in texture files.

1.10.2.2. Parameters

Parameter | Type | Required | Description
--file | Path | true | The texture file
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command displays the contents of the metadata section in the texture file, if one exists.

1.10.3. Examples

1.10.3.1. Example

$ calino show-metadata --file cube-meta.ctf
{
  "DC.Creator" : "Mark Raynsford",
  "DC.Date" : "2022-04-30T12:05:20+00:00",
  "DC.Description" : "A fade texture.",
  "DC.Identifier" : "f9c2cf13-8919-4cfd-b88f-0a6c9e552d59",
  "DC.Rights" : "Public Domain",
  "DC.Title" : "Fade32"
}

$ calino show-metadata --file no-meta.ctf
calino: ERROR: no metadata section is present

1.11. show-sections

1.11.1. Name

1.11.2. Description

1.11.3. Examples

1.11.1. Name

show-sections - Show sections in texture files.

1.11.2. Description

The show-sections command displays the sections present in texture files.

1.11.2.2. Parameters

Parameter | Type | Required | Description
--file | Path | true | The texture file
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command will print one line per section s in the given texture file.

If s is of a type recognized by the implementation, then the line printed for s will be i k (r) @o 'size' n, where i is the index of the section within the file (starting at 0), k is the name of the section, r is the raw 64-bit section identifier, o is the absolute base-16 offset of the start of the section within the file, and n is the base-16 size of the section.

If s is of a type not recognized by the implementation, then the line printed for s will be i r @o 'size' n, where i is the index of the section within the file (starting at 0), r is the raw 64-bit section identifier, o is the absolute base-16 offset of the start of the section within the file, and n is the base-16 size of the section.

1.11.3. Examples

1.11.3.1. Example

$ calino show-sections --file cube-meta.ctf
[ {
  "Name" : "IMAGE_INFO",
  "Index" : 0,
  "Tag" : "434c4e49494e464f",
  "Offset" : "@0x10",
  "Size" : "168"
}, {
  "Name" : "METADATA",
  "Index" : 1,
  "Tag" : "434c4e5f4d455441",
  "Offset" : "@0xd0",
  "Size" : "244"
}, {
  "Name" : "IMAGE_2D",
  "Index" : 2,
  "Tag" : "434c4e5f49324421",
  "Offset" : "@0x1e0",
  "Size" : "4160"
}, {
  "Name" : "END",
  "Index" : 3,
  "Tag" : "434c4e5f454e4421",
  "Offset" : "@0x1230",
  "Size" : "0"
} ]

1.12. show-summary

1.12.1. Name

1.12.2. Description

1.12.3. Examples

1.12.1. Name

show-summary - Summarize texture files.

1.12.2. Description

The show-summary command displays a summary of a texture file.

1.12.2.2. Parameters

Parameter | Type | Required | Description
--file | Path | true | The texture file
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

The command effectively summarizes the data given in the image info section, in addition to optionally listing all of the types, sizes, and offsets of mipmaps in the actual image data if requested with the --show-mipmaps parameter.

1.12.3. Examples

1.12.3.1. Example

$ calino show-summary --file cube-meta.ctf --show-mipmaps true
{
  "Info" : {
    "Version" : "2.0",
    "SizeX" : 256,
    "SizeY" : 256,
    "SizeZ" : 1,
    "Size" : "256×256×1",
    "ChannelLayout" : "R8:G8:B8:A8",
    "ChannelType" : "FIXED_POINT_NORMALIZED_UNSIGNED",
    "ColorSpace" : "SRGB",
    "ByteOrder" : "LITTLE_ENDIAN",
    "Flags" : [ ],
    "CoordinateSystemR" : "RT",
    "CoordinateSystemS" : "SR",
    "CoordinateSystemT" : "TD",
    "CoordinateSystem" : "RT:SR:TD",
    "Compression" : "UNCOMPRESSED",
    "SuperCompression" : "DEFLATE",
    "TexelBlockAlignment" : 32
  },
  "MipMapLevels" : 8,
  "MipMapImages" : 48,
  "MipMaps" : [ {
    "Type" : "Cube",
    "Face" : "X_POSITIVE",
    "Level" : 7,
    "DataOffsetWithinSection" : 1408,
    "SizeCompressed" : 24,
    "SizeUncompressed" : 16,
    "CRC32" : "0x8332c492"
  }, {
    "Type" : "Cube",
    "Face" : "X_NEGATIVE",
    "Level" : 7,
    "DataOffsetWithinSection" : 1440,
    "SizeCompressed" : 24,
    "SizeUncompressed" : 16,
    "CRC32" : "0x8fe06bb7"
  }, {
    "Type" : "Cube",
    "Face" : "Y_POSITIVE",
    "Level" : 7,
    "DataOffsetWithinSection" : 1472,
    "SizeCompressed" : 24,
    "SizeUncompressed" : 16,
    "CRC32" : "0xd3f472a3"
  }, {
    "Type" : "Cube",
    "Face" : "Y_NEGATIVE",
    "Level" : 7,
    "DataOffsetWithinSection" : 1504,
    "SizeCompressed" : 24,
    "SizeUncompressed" : 16,
    "CRC32" : "0xb08db8a4"
  }, {
    "Type" : "Cube",
    "Face" : "Z_POSITIVE",
    "Level" : 7,
    "DataOffsetWithinSection" : 1536,
    "SizeCompressed" : 24,
    "SizeUncompressed" : 16,
    "CRC32" : "0xa5cbe1de"
  }, {
    "Type" : "Cube",
    "Face" : "Z_NEGATIVE",
    "Level" : 7,
    "DataOffsetWithinSection" : 1568,
    "SizeCompressed" : 24,
    "SizeUncompressed" : 16,
    "CRC32" : "0x295a12e7"
  }, {
    "Type" : "Cube",
    "Face" : "X_POSITIVE",
    "Level" : 6,
    "DataOffsetWithinSection" : 1600,
    "SizeCompressed" : 73,
    "SizeUncompressed" : 64,
    "CRC32" : "0x408e6878"
  }, {
    "Type" : "Cube",
    "Face" : "X_NEGATIVE",
    "Level" : 6,
    "DataOffsetWithinSection" : 1696,
    "SizeCompressed" : 70,
    "SizeUncompressed" : 64,
    "CRC32" : "0x6c76c24c"
  }, {
    "Type" : "Cube",
    "Face" : "Y_POSITIVE",
    "Level" : 6,
    "DataOffsetWithinSection" : 1792,
    "SizeCompressed" : 73,
    "SizeUncompressed" : 64,
    "CRC32" : "0x7d9fa7dd"
  }, {
    "Type" : "Cube",
    "Face" : "Y_NEGATIVE",
    "Level" : 6,
    "DataOffsetWithinSection" : 1888,
    "SizeCompressed" : 66,
    "SizeUncompressed" : 64,
    "CRC32" : "0x2801e0b0"
  }, {
    "Type" : "Cube",
    "Face" : "Z_POSITIVE",
    "Level" : 6,
    "DataOffsetWithinSection" : 1984,
    "SizeCompressed" : 70,
    "SizeUncompressed" : 64,
    "CRC32" : "0xd89509c2"
  }, {
    "Type" : "Cube",
    "Face" : "Z_NEGATIVE",
    "Level" : 6,
    "DataOffsetWithinSection" : 2080,
    "SizeCompressed" : 72,
    "SizeUncompressed" : 64,
    "CRC32" : "0x7c21fc8e"
  }, {
    "Type" : "Cube",
    "Face" : "X_POSITIVE",
    "Level" : 5,
    "DataOffsetWithinSection" : 2176,
    "SizeCompressed" : 208,
    "SizeUncompressed" : 256,
    "CRC32" : "0x2f6ae7d4"
  }, {
    "Type" : "Cube",
    "Face" : "X_NEGATIVE",
    "Level" : 5,
    "DataOffsetWithinSection" : 2400,
    "SizeCompressed" : 220,
    "SizeUncompressed" : 256,
    "CRC32" : "0x2db32320"
  }, {
    "Type" : "Cube",
    "Face" : "Y_POSITIVE",
    "Level" : 5,
    "DataOffsetWithinSection" : 2624,
    "SizeCompressed" : 214,
    "SizeUncompressed" : 256,
    "CRC32" : "0x5b566c45"
  }, {
    "Type" : "Cube",
    "Face" : "Y_NEGATIVE",
    "Level" : 5,
    "DataOffsetWithinSection" : 2848,
    "SizeCompressed" : 147,
    "SizeUncompressed" : 256,
    "CRC32" : "0xd9c5b563"
  }, {
    "Type" : "Cube",
    "Face" : "Z_POSITIVE",
    "Level" : 5,
    "DataOffsetWithinSection" : 3008,
    "SizeCompressed" : 207,
    "SizeUncompressed" : 256,
    "CRC32" : "0x9277e9dc"
  }, {
    "Type" : "Cube",
    "Face" : "Z_NEGATIVE",
    "Level" : 5,
    "DataOffsetWithinSection" : 3232,
    "SizeCompressed" : 207,
    "SizeUncompressed" : 256,
    "CRC32" : "0xd8c5be47"
  }, {
    "Type" : "Cube",
    "Face" : "X_POSITIVE",
    "Level" : 4,
    "DataOffsetWithinSection" : 3456,
    "SizeCompressed" : 630,
    "SizeUncompressed" : 1024,
    "CRC32" : "0x338384d4"
  }, {
    "Type" : "Cube",
    "Face" : "X_NEGATIVE",
    "Level" : 4,
    "DataOffsetWithinSection" : 4096,
    "SizeCompressed" : 647,
    "SizeUncompressed" : 1024,
    "CRC32" : "0xfdc3ee12"
  }, {
    "Type" : "Cube",
    "Face" : "Y_POSITIVE",
    "Level" : 4,
    "DataOffsetWithinSection" : 4768,
    "SizeCompressed" : 732,
    "SizeUncompressed" : 1024,
    "CRC32" : "0x21c45396"
  }, {
    "Type" : "Cube",
    "Face" : "Y_NEGATIVE",
    "Level" : 4,
    "DataOffsetWithinSection" : 5504,
    "SizeCompressed" : 383,
    "SizeUncompressed" : 1024,
    "CRC32" : "0xaec67ebe"
  }, {
    "Type" : "Cube",
    "Face" : "Z_POSITIVE",
    "Level" : 4,
    "DataOffsetWithinSection" : 5888,
    "SizeCompressed" : 655,
    "SizeUncompressed" : 1024,
    "CRC32" : "0x48d361e8"
  }, {
    "Type" : "Cube",
    "Face" : "Z_NEGATIVE",
    "Level" : 4,
    "DataOffsetWithinSection" : 6560,
    "SizeCompressed" : 624,
    "SizeUncompressed" : 1024,
    "CRC32" : "0x41b828ce"
  }, {
    "Type" : "Cube",
    "Face" : "X_POSITIVE",
    "Level" : 3,
    "DataOffsetWithinSection" : 7200,
    "SizeCompressed" : 1957,
    "SizeUncompressed" : 4096,
    "CRC32" : "0x6283fb2e"
  }, {
    "Type" : "Cube",
    "Face" : "X_NEGATIVE",
    "Level" : 3,
    "DataOffsetWithinSection" : 9184,
    "SizeCompressed" : 2029,
    "SizeUncompressed" : 4096,
    "CRC32" : "0xc775465e"
  }, {
    "Type" : "Cube",
    "Face" : "Y_POSITIVE",
    "Level" : 3,
    "DataOffsetWithinSection" : 11232,
    "SizeCompressed" : 2461,
    "SizeUncompressed" : 4096,
    "CRC32" : "0xb50386f4"
  }, {
    "Type" : "Cube",
    "Face" : "Y_NEGATIVE",
    "Level" : 3,
    "DataOffsetWithinSection" : 13696,
    "SizeCompressed" : 1073,
    "SizeUncompressed" : 4096,
    "CRC32" : "0xc79c1372"
  }, {
    "Type" : "Cube",
    "Face" : "Z_POSITIVE",
    "Level" : 3,
    "DataOffsetWithinSection" : 14784,
    "SizeCompressed" : 2116,
    "SizeUncompressed" : 4096,
    "CRC32" : "0xbb6c7893"
  }, {
    "Type" : "Cube",
    "Face" : "Z_NEGATIVE",
    "Level" : 3,
    "DataOffsetWithinSection" : 16928,
    "SizeCompressed" : 2017,
    "SizeUncompressed" : 4096,
    "CRC32" : "0xfc260c37"
  }, {
    "Type" : "Cube",
    "Face" : "X_POSITIVE",
    "Level" : 2,
    "DataOffsetWithinSection" : 18976,
    "SizeCompressed" : 6029,
    "SizeUncompressed" : 16384,
    "CRC32" : "0xa745a6c"
  }, {
    "Type" : "Cube",
    "Face" : "X_NEGATIVE",
    "Level" : 2,
    "DataOffsetWithinSection" : 25024,
    "SizeCompressed" : 6326,
    "SizeUncompressed" : 16384,
    "CRC32" : "0xd5f69f72"
  }, {
    "Type" : "Cube",
    "Face" : "Y_POSITIVE",
    "Level" : 2,
    "DataOffsetWithinSection" : 31360,
    "SizeCompressed" : 8407,
    "SizeUncompressed" : 16384,
    "CRC32" : "0x6a0921ef"
  }, {
    "Type" : "Cube",
    "Face" : "Y_NEGATIVE",
    "Level" : 2,
    "DataOffsetWithinSection" : 39776,
    "SizeCompressed" : 2985,
    "SizeUncompressed" : 16384,
    "CRC32" : "0xd3f975e7"
  }, {
    "Type" : "Cube",
    "Face" : "Z_POSITIVE",
    "Level" : 2,
    "DataOffsetWithinSection" : 42784,
    "SizeCompressed" : 6904,
    "SizeUncompressed" : 16384,
    "CRC32" : "0x4e2ed728"
  }, {
    "Type" : "Cube",
    "Face" : "Z_NEGATIVE",
    "Level" : 2,
    "DataOffsetWithinSection" : 49696,
    "SizeCompressed" : 6127,
    "SizeUncompressed" : 16384,
    "CRC32" : "0x5659c068"
  }, {
    "Type" : "Cube",
    "Face" : "X_POSITIVE",
    "Level" : 1,
    "DataOffsetWithinSection" : 55840,
    "SizeCompressed" : 20060,
    "SizeUncompressed" : 65536,
    "CRC32" : "0xc282eabb"
  }, {
    "Type" : "Cube",
    "Face" : "X_NEGATIVE",
    "Level" : 1,
    "DataOffsetWithinSection" : 75904,
    "SizeCompressed" : 20855,
    "SizeUncompressed" : 65536,
    "CRC32" : "0xcecaac65"
  }, {
    "Type" : "Cube",
    "Face" : "Y_POSITIVE",
    "Level" : 1,
    "DataOffsetWithinSection" : 96768,
    "SizeCompressed" : 28385,
    "SizeUncompressed" : 65536,
    "CRC32" : "0xee2008d0"
  }, {
    "Type" : "Cube",
    "Face" : "Y_NEGATIVE",
    "Level" : 1,
    "DataOffsetWithinSection" : 125184,
    "SizeCompressed" : 10618,
    "SizeUncompressed" : 65536,
    "CRC32" : "0x34837ec8"
  }, {
    "Type" : "Cube",
    "Face" : "Z_POSITIVE",
    "Level" : 1,
    "DataOffsetWithinSection" : 135808,
    "SizeCompressed" : 23062,
    "SizeUncompressed" : 65536,
    "CRC32" : "0xc08b7f5c"
  }, {
    "Type" : "Cube",
    "Face" : "Z_NEGATIVE",
    "Level" : 1,
    "DataOffsetWithinSection" : 158880,
    "SizeCompressed" : 20415,
    "SizeUncompressed" : 65536,
    "CRC32" : "0xd637c758"
  }, {
    "Type" : "Cube",
    "Face" : "X_POSITIVE",
    "Level" : 0,
    "DataOffsetWithinSection" : 179296,
    "SizeCompressed" : 68916,
    "SizeUncompressed" : 262144,
    "CRC32" : "0xcd5423b"
  }, {
    "Type" : "Cube",
    "Face" : "X_NEGATIVE",
    "Level" : 0,
    "DataOffsetWithinSection" : 248224,
    "SizeCompressed" : 71069,
    "SizeUncompressed" : 262144,
    "CRC32" : "0x1a641164"
  }, {
    "Type" : "Cube",
    "Face" : "Y_POSITIVE",
    "Level" : 0,
    "DataOffsetWithinSection" : 319296,
    "SizeCompressed" : 95515,
    "SizeUncompressed" : 262144,
    "CRC32" : "0xf912d84d"
  }, {
    "Type" : "Cube",
    "Face" : "Y_NEGATIVE",
    "Level" : 0,
    "DataOffsetWithinSection" : 414816,
    "SizeCompressed" : 49512,
    "SizeUncompressed" : 262144,
    "CRC32" : "0x1c9358a"
  }, {
    "Type" : "Cube",
    "Face" : "Z_POSITIVE",
    "Level" : 0,
    "DataOffsetWithinSection" : 464352,
    "SizeCompressed" : 78958,
    "SizeUncompressed" : 262144,
    "CRC32" : "0x5e12f7c2"
  }, {
    "Type" : "Cube",
    "Face" : "Z_NEGATIVE",
    "Level" : 0,
    "DataOffsetWithinSection" : 543328,
    "SizeCompressed" : 70301,
    "SizeUncompressed" : 262144,
    "CRC32" : "0x29acac90"
  } ],
  "SizeUncompressed" : 2097120
}

1.13. show-version

1.13.1. Name

1.13.2. Description

1.13.3. Examples

1.13.1. Name

show-version - Show a texture file version.

1.13.2. Description

The show-version command displays the format version used by a texture file.

1.13.2.2. Parameters

Parameter | Type | Required | Description
--file | Path | true | The texture file
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

1.13.3. Examples

1.13.3.1. Example

$ calino show-version --file cube-meta.ctf
2.0

1.14. version

1.14.1. Name

1.14.2. Description

1.14.3. Examples

1.14.1. Name

version - Display the Calino tool version

1.14.2. Description

The version command displays the current version of the command-line tool.

1.14.2.2. Parameters

Parameter | Type | Required | Description
--verbose | CLPLogLevel | false | Set the minimum logging verbosity level.

1.14.3. Examples

1.14.3.1. Example

$ calino version
com.io7m.calino 1.0.0

2. API

Documentation for the calino APIs are provided in the form of JavaDoc.