MoonOpenRaster

    OpenRaster layered document editing and compositing in MoonBit

    Download zip
    Author
    Version
    0.2.0
    License
    MIT
    Last updated
    yesterday
    Downloads
    15

    #MoonOpenRaster

    MoonOpenRaster 是用 MoonBit 编写的 OpenRaster(.ora)16 位与 8 位分层栅格图像读写、编辑与合成库,配有命令行和本地网页工作台。

    普通 PNG 只保留最终画面;ORA 还保存独立图层、分组、位置、透明度和混合方式。本项目可以读取这些图层,修改后重新计算画面,再保存为仍可编辑的 ORA。例如:批量隐藏草稿层并导出预览、替换海报中的独立图片层,或为绘图程序添加 ORA 导入与导出功能。

    #能做什么

    • 读取与写入 ORA,保存嵌套图层树、图层属性和可保留的扩展资源。
    • 创建、删除、重命名、复制、重排和跨组移动图层,支持用 PNG、JPEG、静态 WebP、GIF、BMP、TIFF、ICO 或受支持的 SVG 导入和替换图层。
    • 调整可见性、整数位置、不透明度和混合方式,支持 20 种基线 SVG 合成操作及组隔离。
    • 导出整张 PNG、单层 PNG 或全部图层素材;保存 ORA 时重新生成合并预览和缩略图。
    • 在网页中实时预览拖动、撤销重做,并通过四份真实分层作品及三套原创图片格式练习了解图层编辑。

    #体验网页

    需要 MoonBit 0.10.20、Node.js 和 Python 3,以下步骤在完整 GitHub 仓库中运行:

    git clone https://github.com/gywcs101/MoonOpenRaster.git cd MoonOpenRaster moon update python scripts/serve_web.py

    浏览器打开 http://127.0.0.1:8765/,保持终端运行;按 Ctrl+C 停止。端口已占用时可使用 python scripts/serve_web.py --port 8766,并访问相应端口。Windows 使用 PowerShell 也可以直接运行这些命令。

    启动后会载入 David Revoy 的真实分层插画。选择图层后,可以拖动蓝色选框、切换眼睛、修改属性,或在“样例与练习”中跟随指引完成改图,再导出 PNG 或保存 ORA。拖动移动的是整个选中图层,不会自动拆分层内物体;修改图层名称也不会改变画面里的文字。

    点击左侧「导入图片」添加新图层,或选择已有图层后在右侧点击「替换图片」。GIF 取第一帧,TIFF 取第一页。保存 ORA 时,栅格素材存为 PNG,SVG 图层保留原始源文件。打开「样例与练习 → 图片格式练习」,可直接使用案例素材验证八种格式的导入、替换和编辑。支持范围见 兼容矩阵。

    字体和样例随仓库提供,处理期间图像不会上传服务器。浏览器导入上限为 32 MiB。更多操作见 网页使用说明。

    #在 MoonBit 项目中使用

    从 Mooncakes 安装 0.2.0 即可使用 8 位和 16 位图层编辑、自包含静态 SVG 图层及图片格式导入。网页工作台和示例素材随 GitHub 仓库提供。

    moon add gywcs101/MoonOpenRaster@0.2.0

    在使用它的包的 moon.pkg 中添加导入:

    import {
    "gywcs101/MoonOpenRaster" @ora,
    }

    下面的例子创建一个图层、修改名称和位置、合成 PNG,并保存与重新读取 ORA。代码中的 archive 和 png 都是字节数据,文件保存由调用程序处理。

    fn main raise {
    let image = @ora.Image::new(1, 1, [255, 0, 0, 255])
    let layer = @ora.Node::Layer(@ora.Properties::new("红色图层"), image)
    let document = @ora.Document::new(4, 4, [layer])
    let edited = document.set_properties(
    [0],
    @ora.Properties::new("移动后的图层", x=1, y=1),
    )
    let archive = edited.write()
    let reopened = @ora.read(archive)
    let png = reopened.render().encode_png()
    println(png.length())
    }

    这是可执行包示例;在 moon.pkg 中另加 pkgtype(kind: "executable"),然后运行 moon run . --target js。在现有库函数中使用时,无需将包改为可执行类型。

    编辑方法返回新文档,原文档保持不变。路径从栈顶按 0 编号:[0] 表示最上面的节点,[0,2] 表示第一个组内的第三个节点。完整方法、错误约定与更多示例见 库 API 说明。

    #命令行使用

    在克隆的仓库根目录运行,输入路径替换为自己的文件:

    moon run cmd/main --target js -- inspect drawing.ora moon run cmd/main --target js -- render drawing.ora composite.png moon run cmd/main --target js -- edit drawing.ora changed.ora edits.json

    三条命令分别查看图层结构、合成整张 PNG,以及按 JSON 指令修改后保存 ORA。输出路径必须尚不存在。

    edits.json 示例:将第一个组里的第一层改名、移动并设为半透明。省略的属性保留原值,坐标必须为范围内整数。

    [{"path":[0,0],"name":"移动后的图层","x":20,"y":10,"visible":true,"opacity":0.5,"composite_op":"svg:src-over"}]

    #16 位 ORA 往返

    在克隆的仓库根目录运行:

    python scripts/check_rgba16.py

    该命令读取 16 位渐变样例,把嵌套组中的 Light 图层移到 X=9、Y=6 并设为 50% 不透明度,再生成 _build/rgba16/edited.ora 和 edited.png。脚本独立解码输出,检查两个源图层的 16 位样本、重新合成的画面、图层结构与 8 位缩略图。也可以在网页打开同一个样例,手动应用上述属性后保存,重开会保留图层与位深。Krita 重开步骤和结果见 16 位案例与复现说明。

    #SVG 矢量图层

    工作台可以直接导入自包含的静态 SVG,也可以打开引用这类 SVG 的 ORA。图层支持移动、显隐、透明度、混合、复制和排序。合成时按 SVG 的像素尺寸或 viewBox 渲染,保存 ORA 时保留源文件;导出 PNG 时输出合成像素。在「样例与练习 → 地形测绘图」中,可以将 SVG 等高线与 16 位 TIFF 地形放在同一文档。命令行复现运行 python scripts/check_svg.py。

    #兼容性与限制

    • 目标为 OpenRaster 0.0.6 的栅格与受支持的静态 SVG 图层编辑工作流,包括 8 位与 16 位每通道的 sRGB 图层、混合位深、嵌套组、负偏移及 20 种基线合成操作。各图层按原精度保存,含 16 位层时重新生成 16 位合成,归档缩略图为 8 位。
    • 未标记色彩的 PNG 按 sRGB 处理。支持标准 sRGB 标记与经指纹核验的 Krita 非线性 sRGB 配置。线性 RGB、其他 ICC、SVG 子集、文本及未知渲染功能的行为见 兼容矩阵。
    • svg:plus 遵循 W3C 规则,和 Krita Addition 可能有像素差异。Krita 5.3.4 可重开本项目的案例,但实测其 ORA 重存会将图层变回 8 位。
    • 单图和画布最多 16,777,216 像素、单边 16,384,解码图层总预算为 128 MiB。16 位 RGBA 每像素占 8 字节,文件还受归档和渲染缓冲区限制。详见 兼容性与验证记录。

    #文档与许可

    项目代码使用 MIT 许可证。网页中的作品、字体与第三方组件各自遵循其许可,完整文本、来源及修改说明见 LICENSES 和 THIRD_PARTY.md。ZIP、XML 与图片编解码复用 MoonBit 生态组件,OpenRaster 文档语义、编辑与合成在本项目实现。

    OraError

    pub(all) suberror OraError {
    InvalidDocument(String)
    Unsupported(String)
    }

    OraError::message

    fn OraError::message(self : OraError) -> String

    A readable diagnostic preserving the affected resource or property.

    Document

    pub struct Document {
    width : Int
    height : Int
    name : String
    // private fields
    }

    Document::bit_depth

    fn Document::bit_depth(self : Document) -> Int

    Precision of the composite, including the depth of hidden layers.

    Document::children

    fn Document::children(self : Document) -> Array[Node]

    Document::compatibility_warnings

    fn Document::compatibility_warnings(self : Document) -> Array[String]

    Rendering is standards based; this operation can differ from Krita's Addition.

    Document::duplicate

    fn Document::duplicate(self : Document, path : Array[Int], name~ : String) -> Document raise

    Duplicate immediately above the source, including group isolation and extensions.

    Document::height

    fn Document::height(self : Document) -> Int

    Document::insert

    fn Document::insert(self : Document, parent : Array[Int], index : Int, node : Node) -> Document raise

    Document::layer_png

    fn Document::layer_png(self : Document, path : Array[Int]) -> Bytes raise

    Export intrinsic raster pixels, without baking in offset, opacity or blending.

    Document::layers_zip

    fn Document::layers_zip(self : Document) -> Bytes raise

    Flatten raster resources into safely named PNGs with a layers.json manifest.

    Document::move_to

    fn Document::move_to(self : Document, source : Array[Int], parent : Array[Int], index : Int) -> Document raise

    Parent is resolved before removal; index addresses its list after removal. Moving into the source or any of its descendants is rejected.

    Document::name

    fn Document::name(self : Document) -> String

    Document::new

    fn Document::new(width : Int, height : Int, children : Array[Node], name? : String) -> Document raise OraError

    Document::node

    fn Document::node(self : Document, path : Array[Int]) -> Node raise OraError

    Look up a node, detaching any mutable group arrays from the document.

    Document::remove

    fn Document::remove(self : Document, path : Array[Int]) -> Document raise

    Document::render

    fn Document::render(self : Document) -> Image raise OraError

    Document::reorder

    fn Document::reorder(self : Document, path : Array[Int], index : Int) -> Document raise

    Document::replace_children

    fn Document::replace_children(self : Document, children : Array[Node]) -> Document raise OraError

    Document::replace_extra

    fn Document::replace_extra(self : Document, path : Array[Int], attributes : Array[(String, String)]) -> Document raise

    Replace extension attributes without permitting duplicate or reserved keys.

    Document::replace_image

    fn Document::replace_image(self : Document, path : Array[Int], image : Image) -> Document raise

    Document::set_properties

    fn Document::set_properties(self : Document, path : Array[Int], properties : Properties) -> Document raise

    Document::width

    fn Document::width(self : Document) -> Int

    Document::write

    fn Document::write(self : Document) -> Bytes raise

    Image

    pub struct Image {
    width : Int
    height : Int
    // private fields
    }

    Image::bit_depth

    fn Image::bit_depth(self : Image) -> Int

    Image::encode_png

    fn Image::encode_png(self : Image) -> Bytes raise

    Image::height

    fn Image::height(self : Image) -> Int

    Image::new

    fn Image::new(width : Int, height : Int, pixels : Array[Byte]) -> Image raise OraError

    Image::new_rgba16

    fn Image::new_rgba16(width : Int, height : Int, samples : Array[Int]) -> Image raise OraError

    Construct straight RGBA from unsigned 16-bit channel values.

    Image::pixels

    fn Image::pixels(self : Image) -> Array[Byte]

    Image::pixels_rgba16

    fn Image::pixels_rgba16(self : Image) -> Array[Int]

    Copy full-precision samples, promoting 8-bit values by multiplication by 257.

    Image::resize_nearest

    fn Image::resize_nearest(self : Image, width : Int, height : Int) -> Image raise OraError

    Resize for thumbnails and interactive previews; the source remains immutable.

    Image::storage_bytes

    fn Image::storage_bytes(self : Image) -> Int64

    Logical bytes retained by the image and its optional SVG source.

    Image::svg_source

    fn Image::svg_source(self : Image) -> Bytes?

    The original SVG bytes, if this image is backed by a vector layer.

    Image::width

    fn Image::width(self : Image) -> Int

    Isolation

    pub(all) enum Isolation {
    Auto
    Isolate
    }

    Node

    pub(all) enum Node {
    Layer(Properties, Image)
    Group(Properties, Isolation, Array[Node])
    }

    Properties

    pub struct Properties {
    name : String
    x : Int
    y : Int
    visible : Bool
    opacity : Double
    composite_op : String
    // private fields
    }

    Properties::extra

    fn Properties::extra(self : Properties) -> Array[(String, String)]

    A detached copy of extension attributes. Standard attributes use typed setters.

    Properties::new

    fn Properties::new(name : String, x? : Int, y? : Int, visible? : Bool, opacity? : Double, composite_op? : String) -> Properties raise OraError

    archive_entries

    fn archive_entries(data : Bytes) -> Array[(String, Bytes)] raise

    composite_pixel

    fn composite_pixel(backdrop : Array[Double], source : Array[Double], op : String) -> Array[Double] raise OraError

    decode_image

    fn decode_image(data : Bytes) -> Image raise

    Decode a standalone raster or supported SVG image for insertion as a layer. GIF and TIFF import their first frame or page.

    decode_png

    fn decode_png(data : Bytes) -> Image raise

    decode_svg

    fn decode_svg(data : Bytes) -> Image raise

    Read a self-contained static SVG. Keep its exact bytes for ORA write-back and cache a transparent raster for compositing and PNG exports.

    inspect

    fn inspect(data : Bytes) ->
    Json
    raise

    Inspect the document tree and archived preview without decoding layer pixels.

    read

    fn read(data : Bytes) -> Document raise

    validate_preview

    fn validate_preview(data : Bytes, width : Int, height : Int) -> Unit raise

    Validate an archived PNG preview before offering browser read-only mode.

    version

    fn version() -> String