### Navigation

- next
- previous |
- NUKE Python Developer's Guide v11.2v1 documentation »

# Formats

This chapter explains how to handle formats.

## Reading Formats

You can get all the formats in the current NUKE session using nuke.formats(), which returns each format object:

    scriptFormats = nuke.formats()

The format object has all sorts of handy methods, such as the following:

    for f in scriptFormats:
            print f.name()
            print f.width()
            print f.height()
            print f.pixelAspect()
            print 10*'-'

    # Result:
    PC_Video
    640
    480
    1.0
    ----------
    NTSC
    720
    486
    0.910000026226
    ----------
    PAL
    720
    576
    1.09000003338
    ----------
    HD
    1920
    1080
    1.0
    ...

For more methods, check out dir(nuke.Format):

    dir(nuke.Format)
    # Result:
    ['__class__', '__delattr__', '__doc__', '__format__', '__getattribute__', '__hash__', '__init__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'add', 'fromUV', 'height', 'name', 'pixelAspect', 'scaled', 'setHeight', 'setName', 'setPixelAspect', 'setWidth', 'toUV', 'width']

The node object also has a format() method to retrieve its current format. With a node in the Node Graph selected, try:

    node = nuke.selectedNode()
    nodeFormat = node.format()
    print nodeFormat.name()

When having to convert normalized texture space to pixel values of a certain format, fromUV and toUV are very handy. The following always gives you the center of the format in pixel coordinates:

    nodeFormat.fromUV( .5, .5 )
    # Result:
    [1024.0, 778.0]

While this gives you the normalized texture coordinates based on pixel coordinates:

> nodeFormat.toUV( 1024, 788 ) # Result: [0.5, 0.50642675161361694]

## Adding a New Format

To add a new format, you define its parameters as a string using TCl syntax (which basically means the values are delimited by white spaces), then create a new Format object. You need to define at least the width, height, and name to create a new format:

    square2k = '2048 2048 square 2k'
    nuke.addFormat( square2k )

This makes the new format available:

- in all the format menus throughout the UI
- through the Python API.

To add a bounding box or set the pixel aspect ratio, set the respective values between the height and name arguments:

    nuke.addFormat( '2048 2048 48 48 2000 2000 2 square 2k (bbox anamorphic)' )

## Setting Formats

To set a node’s format, simply use the usual knob methods to assign the format by name:

    n = nuke.createNode( 'CheckerBoard2' )
    n['format'].setValue( 'square 2k' )

The same applies when setting the root format::
  nuke.root()[‘format’].setValue( ‘square 2k’ )

To set a format for the root’s proxy knob, you need to first set the root to use the format as the proxy type:

    # DEFINE BASE AND PROXY FORMATS
    square2k = '2048 2048 square 2k'
    square1k = '1024 1024 square 1k'

    # ADD FORMATS TO SESSION
    for f in ( square2k, square1k ):
        nuke.addFormat( f )

    # SET THE ROOT TO USE BOTH BASE AND PROXY FORMATS
    root = nuke.root()
    root['format'].setValue( 'square 2k' )
    root['proxy_type'].setValue( 'format' )
    root['proxy_format'].setValue( 'square 1k' )

### Navigation

- next
- previous |
- NUKE Python Developer's Guide v11.2v1 documentation »