Pixelorama Command Line Interface

[OverloadedOrama]

It would be useful to be able to use Pixelorama's functions directly from the command line, like this https://www.aseprite.org/docs/cli/. I imagine it would help a lot with automation.

It should be possible to do given that Godot has an OS.get_cmdline_args() method for running projects with command line arguments.

[matthewpaul-us]

I'm adding some notes, as I've been doing research on this in the hopes that someone would get enough to work.

Here is a discussion about parsing command line arguments in a game: https://www.reddit.com/r/godot/comments/bomjhc/is_there_any_way_to_pass_arguments_to_the_game/

Here is a version of Godot Server that we could use to run headless. I have no idea if godot has code to determine if we are running via server or a normal version of godot. https://godotengine.org/download/server

What I am not sure about is whether we can use the same pixelorama project and run it headless based on command-line arguments. I took a look around to see if I could find another godot project that has similar capabilities, but didn't find anything.

[gruelingpine185]

Ideas for CLI

Usage

pixelorama [command] [flags...] [files...]

Passing no flags or commands would print data about pixelorama (version, help, etc.)

Example usages

Creating

# create a gif scaled by 200% of frames 4-8 of total frames with a "backwards"
# animation direction, taking frames made in "example.pxo", and outputing as "example.gif"
pixelorama -t image -f gif -d backwards -r "4-8" -s 2.0 example.pxo -o example.gif

# create a gif from list of png files
pixelorama -t image -f gif *.png -o example.gif

# create a spritesheet from list of png files (assuming they are ordered  e.g.`file_01` comes before `file_02`)
pixelorama -t spritesheet ./frames/*.png -o example.gif

Extracting information

# get dimensions of a single frame from project file
$ pixelorama --framesize example.pxo
16x32

# get dimensions of a spritesheet from project file
$ pixelorama --size example.pxo
128x64

# get total frames from project file
$ pixelorama --framecount example.pxo
8

Commands

Maybe instead of the -t flag, you can use commands like these to completely get rid of it:

• image <flags> <image(s)>: Handles image creation of 1 or more images
• spritesheet <flags> <image(s)>: Handles spritesheet creation
• gif <flags> <image(s)>: Handles gif creation
  ...

Flags

• -t <representation type>: Specifies what kind of representation should be used for exporting. One of: image, spritesheet.
  • -f <format>: Specify output format. One of the export formats (e.g. png or gif). Cab be omitted if <representation type> is spritesheet.
• -s <scale float>: Scale output by a factor of $x$, where $x \in (0.0, 10.0]$. (e.g. .5 / 0.5 for 50% original size, 3.5 for 350% original size)
• -d [animation direction]: Sets the animation direction (default is forwards). One of: forwards, backwards, or ping-pong. If no direction is given, print the current direction being used.
• -r <range string>: Selects an inclusive range of frames (e.g. -10, 3-8, or 5-). Not specifying this flag means all frames selected.
• -o <pathname>: Specify output pathname (e.g assets/example.gif) assuming that the path exists. Only outputs to one file.

---

This is just an idea. More can be added, removed, or modified to better fit the capabilities of the editor.

[OverloadedOrama]

Thank you for the ideas. I did some initial work in commit af01234, feel free to try it and let me know what you think. It's not ready yet, but basic exporting should work. I made some changes to your ideas though. Notably, I replaced -t with --export for image exporting, and --spritesheet for spritesheet exporting. I'm not sure if file formats need to be explicitly specified, so what I did is to simply get the extension from the output, and export accordingly. For example -o example.gif will automatically export to gif, while -o example.webp exports to webp.

For most of the short form flags, I replaced them with longer arguments (-s to --scale, -d to --direction, -r to --frames). Ideally we should have both forms, however most of them conflict with Godot's CLI arguments, and thus cannot be used. There is a workaround for this, by using OS.get_cmdline_user_args() instead of OS.get_cmdline_args(), but that would require the CLI to be in the form of

pixelorama example.pxo -- --export -o example.gif

All of our arguments need to come after the double dash (--), but the pxo file name can also come before. Not sure if this ideal, but if we want to keep the short forms of the arguments, this is the only way.

[gruelingpine185]

I'm not sure if file formats need to be explicitly specified, so what I did is to simply get the extension from the output, and export accordingly.

The reason why I had a flag for specifying the file format was because file extensions can possibly be omitted by the invoker, leaving 0 context clues for the CLI to work with. To my knowledge, you can check for the file format in file headers to get the file type for extension-less files, but you still need to know the file type if you are creating the file. Also filenames are just names of files. Say I had a PNG file example.png. I wanted to upload it to a site the expects only JPEG files. If the site doesn't verify the file type, the user can get away with just renaming the file extension to .jpeg. The same can be true for Pixelorama.

All of our arguments need to come after the double dash (--), but the pxo file name can also come before. Not sure if this ideal, but if we want to keep the short forms of the arguments, this is the only way.

You might be able to get away with writing a shell function that acts as an alias for it and telling your users to paste it into their .zshrc,.bashrc files (or whatever people use) If they would like to be get rid if the -- between command and arguments and be able to use short and long form flags. I'm haven't tried the snippet below, but it looks like it can work.

# $1 expected to be a pixelorama project file (*.pxo)
pixel() {
  # handle 0 arguments
  if [[ "$#" == 0 ]]; then
    pixelorama -- -h
    exit "$?"
  fi

  pixelorama "$1" -- "$@"
  exit "$?"
}

I did some initial work in commit af01234, feel free to try it and let me know what you think

Of course I'll try it. When I do, I'll try out the alias function I made above to make sure it works the way I hope it would.