Data Types

The Runway Model SDK provides several data types that can be used to pass values to and from runway models and the applications that control them. The data types currently supported by the SDK are number, text, image, array, vector, category, file, and any, an extensible data type. These data types are primarily used in two places:

  • The options parameter in the @runway.setup() decorator

  • The input and output parameters in @runway.command() decorator

Note

This is example code for demonstration purposes only. It will not run, as the your_code import is not a real python module.

import runway
from runway.data_types import category, vector, image
from your_code import model

options = {"network_size": category(choices=[64, 128, 256, 512], default=256)}
@runway.setup(options=options)
def setup(opts):
    return model(network_size=opts["network_size"])


sample_inputs= {
    "z": vector(length=512),
    "category": category(choices=["day", "night"])
}

sample_outputs = {
    "image": image(width=1024, height=1024)
}

@runway.command("sample", inputs=sample_inputs, outputs=sample_outputs)
def sample(model, inputs):
    img = model.sample(z=inputs["z"], category=inputs["category"])
    # `img` can be a PIL or numpy image. It will be encoded as a base64 URI
    # string automatically by @runway.command().
    return { "image": img }

if __name__ == "__main__":
    runway.run()

Reference

class runway.data_types.BaseType(data_type, description=None)

An abstract class that defines a base data type interface. This type should be used as the base class of new data types, never directly.

Parameters
  • data_type (string) – The data type represented as a string

  • description (string, optional) – A description of this variable and how its used in the model, defaults to None

class runway.data_types.any(description=None)

A generic data type. The value this data type takes must be serializable to JSON.

import yaml
import runway
from runway.data_types import any
from your_code import model

# an example of passing your own yaml configuration using an "any" data_type and PyYAML
@runway.setup(options={ "configuration": any() })
def setup(opts):
    # parse the configuration string as yaml, and then pass the resulting
    # object as the configuration to your model
    config = yaml.load(opts["configuration"])
    return model(config)
Parameters

description (string, optional) – A description of this variable and how its used in the model, defaults to None

class runway.data_types.array(item_type=None, description=None, min_length=0, max_length=None)

A data type representing an array (list) of other runway.data_type objects.

import runway
from runway.data_types import array, text

@runway.setup(options={ "seed_sentences": array(item_type=text, min_length=5) })
def setup(opts):
    for i in range(5):
        print("Sentence {} is "{}"".format(i+1, opts["seed_sentences"][i]))
Parameters
  • item_type (runway.data_type) – A runway.data_type class, or an instance of a runway.data_type class

  • description (string, optional) – A description of this variable and how its used in the model, defaults to None

  • min_length (int, optional) – The minimum number of elements required to be in the array, defaults to 0

  • max_length (int, optional) – The maximum number of elements allowed to be in the array, defaults to None

Raises

MissingArgumentError – A missing argument error if item_type is not specified

class runway.data_types.category(description=None, choices=None, default=None)

A categorical data type that allows you to specify a variable’s value as a member of a set list of choices.

import runway
from runway.data_types import category

# if no default value is specified, the first element in the choices
# list will be used
cat = category(choices=["rgb", "bgr", "rgba", "bgra"], default="rgba")
@runway.setup(options={ "pixel_order": cat })
def setup(opts):
    print("The selected pixel order is {}".format(opts["pixel_order"]))
Parameters
  • description (string, optional) – A description of this variable and how its used in the model, defaults to None

  • choices (A list of strings) – A list of categories, defaults to None

  • default (A list of strings) – A default list of categories, defaults to None

Raises
  • MissingArgumentError – A missing argument error if choices is not a list with at least one element.

  • InvalidArgumentError – An invalid argument error if a default argument is specified and that argument does not appear in the choices list.

class runway.data_types.file(description=None, is_directory=False, extension=None)

A data type that represents a file or directory. The file can be a local resource on disk or a remote resource loaded over HTTP. Instantiate this class to create a new runway model variable.

import runway
from runway.data_types import file, category

inputs = {"directory": file(is_directory=True)}
outputs = {"result": category(choices=["success", "failure"])}
@runway.command("batch_process", inputs=inputs, outputs=outputs)
def batch_process(result_of_setup, args):
    result = do_something_with(args["directory"])
    return { "result": "success" if result else "failure" }
Parameters
  • description (string, optional) – A description of this variable and how its used in the model, defaults to None

  • is_directory (bool, optional) – Does this variable represent a directory instead of a file? Defaults to False.

  • extension (string, optional) – Accept only files of this extension.

class runway.data_types.image(description=None, channels=3, min_width=None, min_height=None, max_width=None, max_height=None, width=None, height=None)

A data type representing an image. Images represent PIL or numpy images but are passed to and from the Model SDK as base64 encoded data URI strings over the network (e.g. data:image/jpeg;base64,/9j/2wCEAAgGBgcG...).

When using an image as an output data type for a function wrapped by @runway.command(), return a PIL or numpy image from your wrapped function and it will automatically be serialized as a base64 encoded data URI.

import runway
from runway.data_types import image

inputs = {"image": image(width=512, height=512)}
outputs = {"image": image(width=512, height=512)}
@runway.command("style_transfer", inputs=inputs, outputs=outputs)
def style_transfer(result_of_setup, args):
    # perform some transformation to the image, and then return it as a
    # PIL image or numpy image
    img = do_style_transfer(args["image"])
    # The PIL or numpy image will be automatically converted to a base64
    # encoded data URI string by the @runway.command() decorator.
    return { "image": img }
Parameters
  • description (string, optional) – A description of this variable and how its used in the model, defaults to None

  • channels (int, optional) – The number of channels in the image, defaults to 3. E.g. an “rgb” image has 3 channels while an “rgba” image has 4.

  • min_width (int, optional) – The minimum width of the image, defaults to None

  • min_height (int, optional) – The minimum height of the image, defaults to None

  • max_width (int, optional) – The maximum width of the image, defaults to None

  • max_height (int, optional) – The maximum height of the image, defaults to None

  • width (int, optional) – The width of the image, defaults to None.

  • height (int, optional) – The height of the image, defaults to None

class runway.data_types.number(description=None, default=0, min=0, max=1, step=1)

A basic number data type. Instantiate this class to create a new runway model variable.

import runway
from runway.data_types import number

@runway.setup(options={ "number_of_samples": number })
def setup(opts):
    print("The number of samples is {}".format(opts["number_of_samples"]))
Parameters
  • description (string, optional) – A description of this variable and how its used in the model, defaults to None

  • default (float, optional) – A default value for this number variable, defaults to 0

  • min (float, optional) – The minimum allowed value of this number type, defaults to 0

  • max (float, optional) – The maximum allowed value of this number type, defaults to 1

  • step (float, optional) – The step size of this number type. This argument define the minimum change of value associated with this number type. E.g., a step size of 0.1 would allow this data type to take on the values [0.0, 0.1, 0.2, ..., 1.0]. Defaults to 1.

class runway.data_types.text(description=None, default='', min_length=0, max_length=None)

A basic text data type. Used to represent strings. Instantiate this class to create a new runway model variable.

import runway
from runway.data_types import text

@runway.setup(options={ "flavor": text(default="vanilla") })
def setup(opts):
    print("The selected flavor is {}".format(opts["flavor"]))
Parameters
  • description (string, optional) – A description of this variable and how its used in the model, defaults to None

  • default (string, optional) – The default value for this text variable, defaults to ‘’

  • min_length (int, optional) – The minimum character length of this text variable, defaults to 0

  • max_length (int, optional) – The maximum character length of this text variable, defaults to None, which allows text to be of any maximum length

class runway.data_types.vector(description=None, length=None, default=None, sampling_mean=0, sampling_std=1)

A data type representing a vector of floats.

import runway
from runway.data_types import vector, number
import numpy as np

inputs={"length": number(min=1)}
outputs={"vector": vector(length=512)}
@runway.command("random_sample", inputs=inputs, outputs=outputs)
def random_sample(result_of_setup, args):
    vec = vector(length=args["length"])
    rand = np.random.random_sample(args["length"])
    return { "vector": vec.deserialize(rand) }
Parameters
  • description (string, optional) – A description of this variable and how its used in the model, defaults to None

  • length (int, inferred if a default vector is specified) – The number of elements in the vector

  • sampling_mean (float, optional) – The mean of the sample the vector is drawn from, defaults to 0

  • sampling_std (float, optional) – The standard deviation of the sample the vector is drawn from, defaults to 1

Raises

MissingArgumentError – A missing argument error if length is not specified