cici-toolkit 0.1.4

Cici: The Microsoft Comic Chat Toolkit

Haiii!! cici is a Microsoft Comic Chat file format library and toolkit.

This toolkit can be used to extract images from .AVB and .BGB files, and in some cases, repair corrupted avatars!

Right now, cici is still in an early alpha form, and only the “info” subcommand is available, with “extract”, “repair” and “scan” to come later. The library itself is still useful for extracting images, but write/repair support is temporarily unavailable.

Soon!

Installing

On Linux/Mac, if you already have Python, this package can be installed from PyPI with pip:

> pip install cici-toolkit

On Windows, you’ll need to install Python first. Go get Python3.11 from the Microsoft Store and install it: https://www.microsoft.com/store/productId/9NRWMJP3717K

Once installed, open up a command prompt and confirm Python and the Python package installer have been installed by typing “pip –version”. If that works, then you should be good to type:

> pip install cici-toolkit

Usage

More in-depth docs coming soon, sorry!

For now, you can use cici info <filename> to see information about any .AVB/.BGB file, and cici info -v <filename> to see in-depth information about a file.

See cici info --help for more details:

usage: cici info [-h] [-e] [-i] [-v] [-s] [--hide-warnings] [-d] filename

positional arguments:
  filename

options:
  -h, --help       show this help message and exit
  -e, --emotions   Show pose/emotion/gesture information
  -i, --images     Show image table information
  -v, --verbose    Verbose output: show emotion and image tables (implies -e, -i)
  -s, --strict     Show pedantic warnings.
  --hide-warnings  Don't show warnings for non-fatal problems with the file.
  -d, --debug      Show full debugging information and stack traces.

To use this as a library, try starting here for now:

>>> import cici

>>> with open("xeno.avb", "rb") as infile:
>>>     avb = cici.Binary(infile)

>>> avb.name
'Xeno'
>>> avb.ftype
<FileType.AVATAR_DYNAMIC: 2>
>>> avb.fvers
<FileVersion.CCHAT_25: 2>

>>> avb.icon
<PIL.BmpImagePlugin.BmpImageFile image mode=P size=40x40 at 0x7F950AC81D60>

>>> img = avb.emotions[0].render()
>>> img
<PIL.Image.Image image mode=RGBA size=120x156 at 0x7F950AC43980>
>>> img.show()

This library uses Pillow to store images in-memory; some familiarity with that API will be helpful for retrieving, converting, and saving images.

Note: Although this library supports dynamic poses (heads and torsos stored separately, like xeno up above), the functionality to composite them is not present in v0.1.0. It’s coming, but needs some cleanup before I publish it; it’s not ready for primetime yet.

Contributing

Patches welcome! Please just send a Merge Request with a pretty good cover letter / commit message. This is still an early version and it is still in heavy development. Just check in with me first before you write a ton of stuff to make sure we aren’t stepping over each other’s toes, ‘kay?

Using the issue tracker would be a great way to coordinate efforts ^_^

Near-future versions will add “repair”, “extract” and “scan” subcommands which will be useful for repairing damage to certain files, extracting all poses/images from files, and scanning a collection of files for duplicates, identifying damaged files, etc.

Changelog

0.1.4 (2024-09-27)

• OK, this is embarrassing. Fixed packaging for commands subpackage …

0.1.3 (2024-09-27)

• Missed another spot in packaging ;_; this time for real …

0.1.2 (2024-09-27)

• Missed a spot in packaging O:-)

0.1.1 (2024-09-27)

• Change package name from “cici” to “cici-toolkit” for PyPI

• Tiny packaging and linting fixes

• Add Binary.write() function back :)

0.1.0 (2024-07-10)

• First release of library and “cici info” command line utility O:-)

  This library may change before v1.0 release and should be considered unstable. I wouldn’t write too much code that relies on this library just yet without coordinating with me a lil’ bit. Each new minor version under major version 0 may break API; I promise no breakages only for micro releases.