Spreadsheet

Read data from a Google Sheet or .csv file.

File - drag in a Google Sheet or .csv asset from the Assets Window.

Column Title - select a column from your spreadsheet. The first row of your spreadsheet is reserved and used to populate this list.

A Spreadsheet node can only output data from a single column. In order to use several columns from the same .csv you need to create a Spreadsheet node for each column you want to output.

Remapping - remap numerical values relative to the lowest and highest number in your data. For example, if you want to create a bar chart and need a value of 1 to be represented by a rectangle with a height of 300px, you can.

If you have a minimum value of 0 and a maximum of 10 within your data and a simple black to white gradient, a value of 0 will be Black, a value of 10 will output White and a value of 5 will be remapped to 50% grey.

Fixed Row - When checked it will output the contents of the row specified in Row Index (not including the title row). Useful for Dynamic Rendering.

Row Index - specify the row to output. A value of 0 outputs row 1 of your spreadsheet (row 0 is reserved for Column Title).

Row Offset - add or subtract a value to Row Index.

Use Every Nth Row - only sample the first and then every Nth row where N = the value.

Row Count - a read only attribute that outputs the number of rows in the selected column.

Example usage:

  1. Create a Text Shape, a Duplicator and a Spreadsheet node.

  2. Create a .csv file containing a row titled 'Name' with several names listed below.

  3. Import the .csv file to the Assets Window.

  4. Drag the .csv into the File attribute of the Spreadsheet node.

  5. Set Column Title to 'Name' on the Spreadsheet node.

  6. Connect textShape.id > duplicator.inputShapes.

  7. Set Count to X = 1 and Y = 4 on the Duplicator.

  8. Connect spreadsheet.id > textShape.text.

You should see the first 4 names from your .csv (not including the title) appear. If you have more or less than 4 names just adjust Count Y on the Duplicator.

Example usage:

  1. Create a Google Sheet containing the data below:

    Label

    Value

    Color

    Twitter

    235

    #00acee

    Instagram

    1135

    #c13584

    YouTube

    101

    #ff0000

    Vimeo

    2301

    #1ab7ea

    TikTok

    764

    #69c9d0

  2. Ensure Link Sharing is set to On and either Public on the web or Anyone with the link.

  3. Import the Google Sheet via the Assets Window.

  4. Drag the Google Sheet asset into the Viewport (this will create a Spreadsheet Element and connect the asset).

  5. Set Column Title to Value.

  6. Create a Rectangle.

  7. Connect spreadsheet.id > rectangle.size.height

  8. Select the Rectangle and alt + click the Duplicator icon in the Shelf.

  9. Set Distribution to Linear.

  10. Set Count to 5.

At this point you should have 5 rectangles each with a height set as per each row of the Value column in your data. In order to pin the rectangles to a 'floor' you can use an Align Behaviour.

  1. Create an Align.

  2. Connect align.id > rectangle.deformers.

  3. On the Align Behaviour, set Y to 1.

If the data contains small/large values then you may need to remap the values to something that produces results that better fit your Composition.

  1. On the Spreadsheet Element set Remapping to Number Range.

  2. Set Source Minimum to 0.

  3. Set Source Maximum to 2500. These to values roughly contain the range of your data.

  4. Set Minimum to 0.

  5. Set Maximum to 500.

A value of 0 in your data will now output as 0 while a value of 2500 will be output at 500. In this example we are effectively dividing all values by 2500/500 = 5 so a value of 1000 would be remapped to 200.

See data.cv in Example Files for an example scene file.

There is a known issue in 1.0.3 where any keyframes for Spreadsheet do not appearing in the Scene Window. You can fix this by manually replacing the basebehaviours.json file in...

  • macOS: Applications/Cavalry.app/Contents/assets/Definitions

  • Windows: C:\Program Files\Cavalry\assets\Definitions

...with the one below. 👇