alpine-alpaca / asefile

Library for loading Aseprite files. Directly reads binary Aseprite files and does not require you to export files to JSON.

asefile

Utilities for loading Aseprite files. This library directly reads the binary Aseprite files (specification) and does not require you to export files to JSON. This should make it fast enough to load your assets when the game boots up (during development). You can also use it to build your own asset pipelines.

Documentation | Changelog

Example

use std::path::Path;

use asefile::AsepriteFile;
use image::{self, ImageFormat};

fn main() {
    let file = Path::new("input.aseprite");
    // Read file into memory
    let ase = AsepriteFile::read_file(&file).unwrap();
    // Write one output image for each frame in the Aseprite file.
    for frame in 0..ase.num_frames() {
        let output = format!("output_{}.png", frame);
        // Create image in memory, then write it to disk as PNG.
        let img = ase.frame(frame).image();
        img.save_with_format(output, ImageFormat::Png).unwrap();
    }
}

Unsupported Features

The following features of Aseprite 1.2.25 are currently not supported:

• color profiles

Bug compatibility

• For indexed color files Aseprite supports blend modes, but ignores them when exporting the image. The images constructed by asefile currently match the in-editor preview.

• Aseprite has a bug in its luminance and color blend modes. Since this is the same in editor and in exported files, asefile reproduces this bug. (If Aseprite fixes this, asefile will fix this bug based on the version that the file was generated with.)

asefile's Issues

Refactoring types and invariants

I'm opening this issue to explore how we can encode some existing panic/assert invariants in static typing. This is one design I'm considering:

pub enum ImageContent {
    Rgba {
        palette: Option<ColorPalette>,
        cels: CelsData<pixel::Rgba>,
        tilesets: TilesetsById<pixel::Rgba>,
    },
    Grayscale {
        palette: Option<ColorPalette>,
        cels: CelsData<pixel::Grayscale>,
        tilesets: TilesetsById<pixel::Grayscale>,
    },
    Indexed {
        palette: ColorPalette,
        transparent_color_index: u8,
        cels: CelsData<pixel::Indexed>,
        tilesets: TilesetsById<pixel::Indexed>,
    },
}

Any invariant behavior around the pixel format (a palette must be present, etc) would be encoded in this single ImageContent enum. This would replace the PixelFormat and Pixels enums, and additionally contain the dependent data. Cels and Tilesets would become generic over a pixel type.

Cels and Tilesets also contain a lot of non-pixel metadata. Making these types generic would make it harder to work with all of the non-image content. I also considered a design where the pixel data would live in a separate map from the non-pixel metadata:

// Only these pixel tables are generic.
// The rest of the data remains non-generic, in the existing top-level maps.
// This would prevent the generic types from "leaking" into other code that touches cels or tilesets.
pub struct CelPixelsById<T>(HashMap<CelId, Vec<T>>);
pub struct TilesetPixelsById<T>(HashMap<TilesetId, Vec<T>>);

pub enum ImagePixelContent {
    Rgba {
        palette: Option<ColorPalette>,
        cels: CelPixelsById<pixel::Rgba>,
        tilesets: TilesetPixelsById<pixel::Rgba>,
    },
    // etc
}

This indirection would allow users to use Tilesets and Cels from multiple files without regard for their pixel format.

"Indexed colors without a palette" for indexed image that has a palette

Asefile does not seem to think that this indexed color image has a palette, even though it has a full 256-color palette stored in it. Here's what it looks like in Aseprite:

For some reason this gives Invalid Aseprite input: Indexed colors without a palette

The source .ase file (had to zip this or Github wouldn't let me attach it):
animation_tracks.ase.zip

TilesetsById iterator

The map function for TilesetsById has been commented out. Without it, it's impossible to iterate over entries within the inner HashMap. It would be nice to either reinstate the method (rust naming conventions suggest this method be called .inner()), or implement other access methods like a custom iterator.

Indexed color pixel access

Hi, thanks for making this library!

Right now the only way to get the image contents is in already-processed RGBA pixels (via the 'image' crate, which isn't exactly a lightweight dependency). Since Aseprite is a pixel art editor, and it already exports indexed-color PNGs, it would be nice to be able to get the indexed color pixels in this library too.

This is going to be used for an asset pipeline to an engine that knows how to load indexed-color images (and may do more with them in the future).

At the very least I'd like to have access to the raw source image data (width, height, color format, palette, pixel data as array of bytes). Unfortunately the raw form is currently not exposed to consumers of the library as it's marked with pub(crate). Could this be opened up? Not everyone wants to use the high-level image-driven interface.

Thanks in advance!

Layer opacity ignored when constructing image

When constructing an image::RgbaImage through AsepriteFile::frame_image(&self, frame: u16), layer's opacity is completely ignored, which leaves to a wrong image result (comparing with aseprite itself)

Combine forces with ggez/aseprite crate

Since yesterday I've become a maintainer for the ggez/aseprite crate.

Since the aseprite crate is purely focused on parsing exported JSON, and this crate is focussed on parsing .aseprite files, I think it would be nice to somehow combine them or at least collaborate.

From a user's perspective, I think a workflow where you can work with the .aseprite files directly, ideally with hot reloading, and during a release build the JSON with a sprite sheet can be exported and bundled. I'm not sure how exactly this would look.

What are your thoughts on this?

Bug: cel's is_empty function works as opposite

https://github.com/alpine-alpaca/asefile/blob/ce656f61d1c0671f1f600d2ec6be9903e24898d3/src/cel.rs#L35C1-L37

Public-facing constructors

Currently, most asefile structs hide their fields and expose immutable access methods. To support use cases around testing and actually manipulating Aseprite files from code, we'll need to allow some level of public-facing constructor and/or mutation support.

v1.3 Updates

Aseprite v1.3 will bring some changes to the Aseprite file specification. This includes a few new types of data:

• Cel types
• User data chunks, one per tag
• Tileset chunks