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. Name

1.2. Description

1.2. Examples

1.3. create-2d

1.3. Name

1.3. Description

1.3. Examples

1.4. create-array

1.4. Name

1.4. Description

1.4. Examples

1.5. create-cube

1.5. Name

1.5. Description

1.5. Examples

1.6. extract-image-data-2d

1.6. Name

1.6. Description

1.6. Examples

1.7. extract-image-data-array

1.7. Name

1.7. Description

1.7. Examples

1.8. extract-image-data-cube

1.8. Name

1.8. Description

1.8. Examples

1.9. show-image-info

1.9. Name

1.9. Description

1.9. Examples

1.10. show-metadata

1.10. Name

1.10. Description

1.10. Examples

1.11. show-sections

1.11. Name

1.11. Description

1.11. Examples

1.12. show-summary

1.12. Name

1.12. Description

1.12. Examples

1.13. show-version

1.13. Name

1.13. Description

1.13. Examples

1.14. version

1.14. Name

1.14. Description

1.14. 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. Name

1.2. Description

1.2. 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. Name

1.3. Description

1.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. Name

1.4. Description

1.4. 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. Name

1.5. Description

1.5. 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. Name

1.6. Description

1.6. 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. Name

1.7. Description

1.7. 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. Name

1.8. Description

1.8. 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. Name

1.9. Description

1.9. 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
Size                    : 256×256×6
Channel Layout          : R8:G8:B8:A8
Channel Type            : FIXED_POINT_NORMALIZED_UNSIGNED
Color Space             : SRGB
Flags                   :
Coordinate System       : RT:SR:TD
Compression             : UNCOMPRESSED
Super Compression       : UNCOMPRESSED
Texel Block Alignment   : 32 octets

1.10. show-metadata

1.10. Name

1.10. Description

1.10. 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 cube texture.]
DC.Identifier: [9c2923a7-abe7-4ff4-8037-334a093db6da]
DC.Rights: [Public Domain]
DC.Title: [Deguelia Utilis]

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

1.11. show-sections

1.11. Name

1.11. Description

1.11. 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
0 IMAGE_INFO (434c4e49494e464f) @10 size b0
1 METADATA (434c4e5f4d455441) @d0 size 100
2 IMAGE_CUBE (434c4e5f43554245) @1e0 size 2005d0
3 END (434c4e5f454e4421) @2007c0 size 0

1.12. show-summary

1.12. Name

1.12. Description

1.12. 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
calino 1.0 texture: 256×256×1 R8:G8:B8:A8 FIXED_POINT_NORMALIZED_UNSIGNED little-endian (8 mipmap levels, 48 images)
mipMapCube (level 7) (face X_POSITIVE) (offset 1408) (size-compressed 16) (size-uncompressed 16) (crc32 0x8332c492)
mipMapCube (level 7) (face X_NEGATIVE) (offset 1440) (size-compressed 16) (size-uncompressed 16) (crc32 0x8fe06bb7)
mipMapCube (level 7) (face Y_POSITIVE) (offset 1472) (size-compressed 16) (size-uncompressed 16) (crc32 0xd3f472a3)
mipMapCube (level 7) (face Y_NEGATIVE) (offset 1504) (size-compressed 16) (size-uncompressed 16) (crc32 0xb08db8a4)
mipMapCube (level 7) (face Z_POSITIVE) (offset 1536) (size-compressed 16) (size-uncompressed 16) (crc32 0xa5cbe1de)
mipMapCube (level 7) (face Z_NEGATIVE) (offset 1568) (size-compressed 16) (size-uncompressed 16) (crc32 0x295a12e7)
mipMapCube (level 6) (face X_POSITIVE) (offset 1600) (size-compressed 64) (size-uncompressed 64) (crc32 0x408e6878)
mipMapCube (level 6) (face X_NEGATIVE) (offset 1664) (size-compressed 64) (size-uncompressed 64) (crc32 0x6c76c24c)
mipMapCube (level 6) (face Y_POSITIVE) (offset 1728) (size-compressed 64) (size-uncompressed 64) (crc32 0x7d9fa7dd)
mipMapCube (level 6) (face Y_NEGATIVE) (offset 1792) (size-compressed 64) (size-uncompressed 64) (crc32 0x2801e0b0)
mipMapCube (level 6) (face Z_POSITIVE) (offset 1856) (size-compressed 64) (size-uncompressed 64) (crc32 0xd89509c2)
mipMapCube (level 6) (face Z_NEGATIVE) (offset 1920) (size-compressed 64) (size-uncompressed 64) (crc32 0x7c21fc8e)
mipMapCube (level 5) (face X_POSITIVE) (offset 1984) (size-compressed 256) (size-uncompressed 256) (crc32 0x2f6ae7d4)
mipMapCube (level 5) (face X_NEGATIVE) (offset 2240) (size-compressed 256) (size-uncompressed 256) (crc32 0x2db32320)
mipMapCube (level 5) (face Y_POSITIVE) (offset 2496) (size-compressed 256) (size-uncompressed 256) (crc32 0x5b566c45)
mipMapCube (level 5) (face Y_NEGATIVE) (offset 2752) (size-compressed 256) (size-uncompressed 256) (crc32 0xd9c5b563)
mipMapCube (level 5) (face Z_POSITIVE) (offset 3008) (size-compressed 256) (size-uncompressed 256) (crc32 0x9277e9dc)
mipMapCube (level 5) (face Z_NEGATIVE) (offset 3264) (size-compressed 256) (size-uncompressed 256) (crc32 0xd8c5be47)
mipMapCube (level 4) (face X_POSITIVE) (offset 3520) (size-compressed 1024) (size-uncompressed 1024) (crc32 0x338384d4)
mipMapCube (level 4) (face X_NEGATIVE) (offset 4544) (size-compressed 1024) (size-uncompressed 1024) (crc32 0xfdc3ee12)
mipMapCube (level 4) (face Y_POSITIVE) (offset 5568) (size-compressed 1024) (size-uncompressed 1024) (crc32 0x21c45396)
mipMapCube (level 4) (face Y_NEGATIVE) (offset 6592) (size-compressed 1024) (size-uncompressed 1024) (crc32 0xaec67ebe)
mipMapCube (level 4) (face Z_POSITIVE) (offset 7616) (size-compressed 1024) (size-uncompressed 1024) (crc32 0x48d361e8)
mipMapCube (level 4) (face Z_NEGATIVE) (offset 8640) (size-compressed 1024) (size-uncompressed 1024) (crc32 0x41b828ce)
mipMapCube (level 3) (face X_POSITIVE) (offset 9664) (size-compressed 4096) (size-uncompressed 4096) (crc32 0x6283fb2e)
mipMapCube (level 3) (face X_NEGATIVE) (offset 13760) (size-compressed 4096) (size-uncompressed 4096) (crc32 0xc775465e)
mipMapCube (level 3) (face Y_POSITIVE) (offset 17856) (size-compressed 4096) (size-uncompressed 4096) (crc32 0xb50386f4)
mipMapCube (level 3) (face Y_NEGATIVE) (offset 21952) (size-compressed 4096) (size-uncompressed 4096) (crc32 0xc79c1372)
mipMapCube (level 3) (face Z_POSITIVE) (offset 26048) (size-compressed 4096) (size-uncompressed 4096) (crc32 0xbb6c7893)
mipMapCube (level 3) (face Z_NEGATIVE) (offset 30144) (size-compressed 4096) (size-uncompressed 4096) (crc32 0xfc260c37)
mipMapCube (level 2) (face X_POSITIVE) (offset 34240) (size-compressed 16384) (size-uncompressed 16384) (crc32 0xa745a6c)
mipMapCube (level 2) (face X_NEGATIVE) (offset 50624) (size-compressed 16384) (size-uncompressed 16384) (crc32 0xd5f69f72)
mipMapCube (level 2) (face Y_POSITIVE) (offset 67008) (size-compressed 16384) (size-uncompressed 16384) (crc32 0x6a0921ef)
mipMapCube (level 2) (face Y_NEGATIVE) (offset 83392) (size-compressed 16384) (size-uncompressed 16384) (crc32 0xd3f975e7)
mipMapCube (level 2) (face Z_POSITIVE) (offset 99776) (size-compressed 16384) (size-uncompressed 16384) (crc32 0x4e2ed728)
mipMapCube (level 2) (face Z_NEGATIVE) (offset 116160) (size-compressed 16384) (size-uncompressed 16384) (crc32 0x5659c068)
mipMapCube (level 1) (face X_POSITIVE) (offset 132544) (size-compressed 65536) (size-uncompressed 65536) (crc32 0xc282eabb)
mipMapCube (level 1) (face X_NEGATIVE) (offset 198080) (size-compressed 65536) (size-uncompressed 65536) (crc32 0xcecaac65)
mipMapCube (level 1) (face Y_POSITIVE) (offset 263616) (size-compressed 65536) (size-uncompressed 65536) (crc32 0xee2008d0)
mipMapCube (level 1) (face Y_NEGATIVE) (offset 329152) (size-compressed 65536) (size-uncompressed 65536) (crc32 0x34837ec8)
mipMapCube (level 1) (face Z_POSITIVE) (offset 394688) (size-compressed 65536) (size-uncompressed 65536) (crc32 0xc08b7f5c)
mipMapCube (level 1) (face Z_NEGATIVE) (offset 460224) (size-compressed 65536) (size-uncompressed 65536) (crc32 0xd637c758)
mipMapCube (level 0) (face X_POSITIVE) (offset 525760) (size-compressed 262144) (size-uncompressed 262144) (crc32 0xcd5423b)
mipMapCube (level 0) (face X_NEGATIVE) (offset 787904) (size-compressed 262144) (size-uncompressed 262144) (crc32 0x1a641164)
mipMapCube (level 0) (face Y_POSITIVE) (offset 1050048) (size-compressed 262144) (size-uncompressed 262144) (crc32 0xf912d84d)
mipMapCube (level 0) (face Y_NEGATIVE) (offset 1312192) (size-compressed 262144) (size-uncompressed 262144) (crc32 0x1c9358a)
mipMapCube (level 0) (face Z_POSITIVE) (offset 1574336) (size-compressed 262144) (size-uncompressed 262144) (crc32 0x5e12f7c2)
mipMapCube (level 0) (face Z_NEGATIVE) (offset 1836480) (size-compressed 262144) (size-uncompressed 262144) (crc32 0x29acac90)

1.13. show-version

1.13. Name

1.13. Description

1.13. 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
version: 1.0

1.14. version

1.14. Name

1.14. Description

1.14. 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.