Skip to content

The scene file, renders and movies

Save the scene, render frames, write movies and cut a movie into pictures.

These calls work on the scene's file and window, write pictures and movies, and read what the product says it is. Most of them need the editor window. In a script run from the command line, the file and window calls throw NO_EDITOR.

The scene's file

buhayin.scene.*

buhayin.scene is a function (buhayin.scene(frame?) reads the scene) and also holds these calls.

await buhayin.scene.currentScene()          // the scene's file name without its ending
await buhayin.scene.currentProjectPath()    // the project's folder
await buhayin.scene.currentContainerPath()  // the same folder
await buhayin.scene.description()
await buhayin.scene.setDescription(text)
await buhayin.scene.saveAsNewVersion(name)
await buhayin.scene.saveAll()
await buhayin.scene.saveAs(path)
await buhayin.scene.isDirty()
await buhayin.scene.hasBeenDirty()
await buhayin.scene.closeScene()
await buhayin.scene.closeSceneAndOpenOffline(path)
await buhayin.scene.closeSceneAndOpen("", project, scene)
await buhayin.scene.closeSceneAndExit()
await buhayin.scene.getFrameRate()
await buhayin.scene.setFrameRate(fps, keepSeconds?)
CallWhat it does
currentScene, currentProjectPath, currentContainerPathWhere the scene is kept.
description, setDescriptionThe text saveAsNewVersion(name) writes with the version.
saveAsNewVersion(name)Keeps a named version beside the scene, with the description.
saveAll, saveAs(path)Save to the scene's own file, or to a path.
isDirty, hasBeenDirtyWhether there are changes since the last save, and whether anything has been done since the scene opened.
closeScene, closeSceneAndOpenOffline(path)Close the window as File does, asking about unsaved work. The second opens the file at path in its place.
closeSceneAndOpen("", project, scene)Opens the scene scene of the project folder project in your projects folder. The first argument is ignored.
closeSceneAndExitCloses every window, as File > Quit does.
getFrameRate, setFrameRate(fps, keepSeconds?)Read and set the frame rate. Setting it also gives the rate to the project's other scenes, and the window says so in a notice.

Each of these gives false when it could not be done. Buhayin has no environments, jobs or versions of its own. currentEnvironment(), currentEnvironmentPath(), currentJob(), currentJobPath(), tempProjectPath() and tempProjectPathRemapped() give an empty string, currentVersion() gives 1, currentVersionName() is empty and isCurrentProjectCompressed() is false. currentProjectPathRemapped() is the project's folder, as currentProjectPath() is. closeSceneAndOpen opens nothing and gives false when you name a version or ask for a read only open.

if (await buhayin.scene.isDirty()) {
  await buhayin.scene.saveAll()
  print("Saved")
}

Elements

buhayin.element

await buhayin.element.numberOf()
await buhayin.element.id(index)
await buhayin.element.getNameById(id)
await buhayin.element.renameById(id, name)
await buhayin.element.add(name, scanType, fieldChart, fileFormat, vectorFormat)
await buhayin.element.remove(id, deleteDiskFile)
await buhayin.element.scanType(id)
await buhayin.element.fieldChart(id)
await buhayin.element.vectorType(id)
await buhayin.element.pixmapFormat(id)
await buhayin.element.isPacked(id)
await buhayin.element.folder(id)
await buhayin.element.completeFolder(id)
await buhayin.element.physicalName(id)
await buhayin.element.modify(id, scanType, fieldChart, pixmapFormat, vectorType)

An element is a set of drawings that rows show. The scene names an element. A script holds it by a whole number the run gives each name the first time it sees it, in the scene's order. add takes "COLOR", "GRAY_SCALE" or "BW" as the scan type and gives the new element's number. Calls that cannot be done give false or -1.

An element has no scan type, chart or file format of its own to change. modify is true only when you ask for what the element already is, and changes nothing.

const count = await buhayin.element.numberOf()
for (let i = 0; i < count; i++) {
  print(await buhayin.element.getNameById(await buhayin.element.id(i)))
}

Rendering pictures

buhayin.render

await buhayin.render.renderScene(from, to)
await buhayin.render.renderSceneAll()
await buhayin.render.renderNodes(layers, from, to)
await buhayin.render.renderNodes(layers, frames)
buhayin.render.setResolution(x, y)
buhayin.render.setResolutionName(name)
buhayin.render.setBgColor(colour)
buhayin.render.setWhiteBackground(on)
buhayin.render.setRenderDisplay(name)
buhayin.render.setWriteEnabled(on)
buhayin.render.cancelRender()
buhayin.render.disconnect()

Renders a PNG sequence into a folder called frames beside the scene. If you moved the run's folder with buhayin.dir.cd, it goes in frames there.

  • renderScene(from, to) renders those frames. renderSceneAll() renders every frame. renderNodes renders the named layers, for a range or for a list of frames.
  • setResolution(x, y) sets the size in pixels, or setResolutionName(name) takes one of the scene's named resolutions.
  • setBgColor({ r, g, b, a }) sets the background, each channel 0 to 255. A background with a of 0 renders transparent. setWhiteBackground(true) sets white.
  • setRenderDisplay(name) chooses a display node when the scene has several.
  • setWriteEnabled(false) renders without keeping the pictures.
  • A render whose first frame is after its last, or that starts below frame 1, does nothing.
  • setCombine, setAutoThumbnailCropping and setFieldType are accepted and change nothing, so a script written for another renderer still runs.

frameReady, nodeFrameReady and renderFinished are signals. Connect a function and it is called as frames are written.

buhayin.render.frameReady.connect((frame, cel) => print("Frame " + frame + " is at " + cel.imageFile()))
await buhayin.render.renderScene(1, 12)

A cel is { frame, imageFile, imageFileAs }. imageFile() is where the render wrote the picture. imageFile(path) copies it to path. imageFileAs(path, format) does the same for an empty format or "PNG" and gives null for any other. cancelRender() from inside one of the functions stops the rest. The wait for frames does not count against the script's time.

Writing movies

buhayin.exporter

await buhayin.exporter.exportToQuicktime(codec, from, to, withSound, resX, resY, path, display)
await buhayin.exporter.exportOGLToQuicktime(name, folder, from?, to?, resX?, resY?)
await buhayin.exporter.getExportDir()
await buhayin.exporter.cleanExportDir()

exportToQuicktime writes a movie to path, replacing the file there once the movie is whole. codec is read by what it contains: prores, with proxy, lt, hq or 4444, gives a MOV in ProRes. vp9 or webm gives a WebM. Anything else, or nothing, gives H.264 in an MP4. It gives true when the movie was written. exportOGLToQuicktime writes an MP4 called name into folder, over the scene's playback range unless you give both frames.

getExportDir() gives the run's export folder, made if needed, with a slash at the end. cleanExportDir() empties it.

const folder = await buhayin.exporter.getExportDir()
const done = await buhayin.exporter.exportToQuicktime("h264", 1, 24, true, 0, 0, folder + "test.mp4", "")
print(done ? "Written" : "Not written")

Cutting a movie into pictures

buhayin.movieImport

buhayin.movieImport.setMovieFilename(path)
buhayin.movieImport.setImageFolder(path)
buhayin.movieImport.setImagePrefix(prefix)
buhayin.movieImport.setAudioFile(path)
await buhayin.movieImport.doImport()
buhayin.movieImport.numberOfImages()
buhayin.movieImport.image(index)
buhayin.movieImport.isAudioFileCreated()

Set up the movie, the folder for the pictures, a name prefix and a sound file, then call doImport(). It cuts the movie into numbered PNG pictures named prefix-1.png and on, and writes its sound to the audio file. It gives true when it worked. setStartFrame and setStopFrame are accepted and change nothing. Afterwards numberOfImages() counts the pictures, image(index) names one and isAudioFileCreated() says whether the sound was written. The wait does not count against the script's time.

A drawing as an exporter reads it

buhayin.drawingExport.getDrawingData(args)

await buhayin.drawingExport.getDrawingData({ drawing: { elementId, exposure } })

A drawing as { box, arts, colors }. Each art holds its layers of contours, its strokes with their thickness paths, and the colours used. Give the element's number and the drawing's name.

What the product is

buhayin.about

buhayin.about.isStoryboard()
buhayin.about.getMajorVersion()
buhayin.about.getUserName()
buhayin.about.userName          // the same, as a property

Answers at once, with no await, what the product says it is. Most calls also exist as a property, so buhayin.about.userName is buhayin.about.getUserName(). There are calls for the version (getMajorVersion, getMinorVersion, getPatchVersion, getBuildNumber), the paths (getApplicationPath, getBinaryPath, getResourcesPath), the platform (isMacArch, isLinuxArch, isWindowsArch) and what kind of window the script runs in (isStoryboard, isInteractiveApp, isMainApp).