# Calino User Manual
| Property | Value |
| --- | --- |
| 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
- [1. Command-Line Interface](#d0e37)
- [1.1. Overview](#d0e39)
- [1.2. check](#d0e62)
- [1.3. create-2d](#d0e198)
- [1.4. create-array](#d0e496)
- [1.5. create-cube](#d0e813)
- [1.6. extract-image-data-2d](#d0e1224)
- [1.7. extract-image-data-array](#d0e1427)
- [1.8. extract-image-data-cube](#d0e1634)
- [1.9. show-image-info](#d0e1888)
- [1.10. show-metadata](#d0e1978)
- [1.11. show-sections](#d0e2068)
- [1.12. show-summary](#d0e2227)
- [1.13. show-version](#d0e2320)
- [1.14. version](#d0e2404)
- [2. API](#id_5005626a-6963-445b-b583-966295367fb8)
## 1. Command-Line Interface
## 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](#id_5005626a-6963-445b-b583-966295367fb8). Applications wishing to do more advanced image processing should use those APIs directly.
## 1.2. check
### 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](https://www.io7m.com/software/calino/specification/index.xhtml). 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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_499041fb-7c35-4fa6-be6b-895962e6e717).
The **--metadata** parameter specifies a file containing key/value metadata in [Java properties](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Properties.html) 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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_499041fb-7c35-4fa6-be6b-895962e6e717).
The **--metadata** parameter specifies a file containing key/value metadata in [Java properties](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Properties.html) 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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_499041fb-7c35-4fa6-be6b-895962e6e717).
The **--metadata** parameter specifies a file containing key/value metadata in [Java properties](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Properties.html) 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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_8f83a47a-986e-4dba-bfd7-720641cee3a9) (such as [LZ4](https://lz4.github.io/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](https://en.wikipedia.org/wiki/Portable_Network_Graphics) 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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_8f83a47a-986e-4dba-bfd7-720641cee3a9) (such as [LZ4](https://lz4.github.io/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](https://en.wikipedia.org/wiki/Portable_Network_Graphics) 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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_8f83a47a-986e-4dba-bfd7-720641cee3a9) (such as [LZ4](https://lz4.github.io/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](https://en.wikipedia.org/wiki/Portable_Network_Graphics) 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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_bc0e7016-7dab-4edb-a4c9-2b1492da0225) 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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_16fddeaf-9d7f-437b-8662-01e6975f6249) 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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_ae85d70d-f1db-4288-8b92-b48580133c33), **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](https://www.io7m.com/software/calino/specification/index.xhtml#id_ae85d70d-f1db-4288-8b92-b48580133c33), **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
**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](https://www.io7m.com/software/calino/specification/index.xhtml#id_bc0e7016-7dab-4edb-a4c9-2b1492da0225) 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
**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
**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](https://documentation.io7m.com/calino/apidocs).