No description or website provided.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.md

README.md

Collectarium Database Format

Introduction

Collectarium is an iPad app that lets you organize collections of objects through a flexible structure. You can find more information at this address: http://www.creaceed.com/collectarium

Because you'll possibly be spending a lot of time encoding data and taking pictures in Collectarium, we want to allow options to offer free access to your data, and not keep it captive within the app.

That's why we offer an option to export the underlying database either for sharing, backup, or other purpose. You'll find the documentation of the format and conventions made by the app.

Document Structure

Exporting a collection with Collectarium creates a .collectarium file. This file is a TAR archive that you can extract with any TAR-compatible tool.

MyCollection.collectarium

Once extracted, you'll notice the following structure (.zip contents is displayed as extracted).

MyCollection/
    data.zip/
        collection.plist
        FEB62725-E7D1-4305-AF85-79A3D503E1CF.jpg # thumbnail
        series/
            10C95FD2-DE20-47E9-A530-657775062BBB/
                database.db
                series.plist
                5A20AB71-38F8-43E9-B6E3-C539D6008E0C.jpg # thumbnail
            38F3CD03-FB05-4998-BB29-7889548C2335/
            ...

    images/
        10C95FD2-DE20-47E9-A530-657775062BBB/
            B672A744-27DE-4978-BB83-94CE86936E28.jpg
            E280FE5E-9372-435A-A6DC-02DE1879CA80.jpg
            ...
        38F3CD03-FB05-4998-BB29-7889548C2335/
        ...

The exported collection has 2 parts:

  • data.zip which holds metadata, database data, and thumbnail.
  • images folder which contains full-resolution images for each series of the collection

If you look closely, you'll notice that there is a correspondence between folder names under 'series', and folder names under 'images', as each series gets it own image folder (JPGs are saved outside of the zip for obvious reasons).

collection.plist Format

collection.plist is a plist file that holds collection metadata. It has the following format:

<plist version="1.0">
<dict>
    <key>collection</key>
    <dict>
        <key>columnDefaults</key>
        <array/>
        <key>coverImageFilename</key>
        <string>6EB62725-E7D1-4305-AF85-79A3D503E1CF.jpg</string>
        <key>identifier</key>
        <string>C4930006-C929-489A-BD6D-E714D0573D17</string>
        <key>name</key>
        <string>Timbres</string>
        <key>resume</key>
        <string>Belgique</string>
        <key>seriesIdentifiers</key>
        <array>
            <string>38F3CD03-FB05-4998-BB29-7889548C2335</string>
            <string>6493B22A-56EF-415F-92F4-26FD1ECAE9C4</string>
        </array>
    </dict>
    <key>metadata</key>
    <dict>
        <key>creationdate</key>
        <date>2016-03-25T08:02:04Z</date>
    </dict>
</dict>
</plist>
  • 'name' key provides collection name, and 'identifier' the collection's unique identifier (used during export / import)
  • 'seriesIdentifiers' match the series folders mentioned above.
  • 'coverImageFilename' provides the filename of collection thumbnail.
  • 'resume' is for a short description for the collection
  • 'metadata' provides a dictionary of metadata (only 'creationDate' for now)

series.plist Format

series.plist is a plist file that holds series metadata. In particular, the template for cards (individual fields) are described in the file. It has the following format (see below).

In particular, notice each field (for card that are part of this series) is defined here, and gets a name, type, unique identifier, and default value.

<plist version="1.0">
<dict>
    <key>completed</key>
    <false/>
    <key>coverImageFilename</key>
    <string>5A20AB71-38F8-43E9-B6E3-C539D6008E0Cjpg</string>
    <key>creationDate</key>
    <date>2016-03-25T08:04:06Z</date>
    <key>fieldAttributes</key>
    <dict>
        <key>Coll15EFF616B7CD4B5C8956182183F093B1</key>
        <dict>
            <key>defaultValue</key>
            <real>1.2</real>
            <key>identifier</key>
            <string>Coll15EFF616B7CD4B5C8956182183F093B1</string>
            <key>name</key>
            <string>Price (new)</string>
            <key>range</key>
            <integer>0</integer>
            <key>type</key>
            <integer>4</integer>
            <key>unit</key>
            <integer>0</integer>
        </dict>
    </dict>
    <key>modificationDate</key>
    <date>2016-03-25T08:02:04Z</date>
    <key>name</key>
    <string>Fleurs (1990)</string>
    <key>numberOfCards</key>
    <integer>3</integer>
    <key>orderedFieldAttributeIdentifiers</key>
    <array>
        <string>name</string>
        <string>reference</string>
        <string>creation_date</string>
        <string>modification_date</string>
        <string>completed</string>
        <string>Coll15EFF616B7CD4B5C8956182183F093B1</string>
    </array>
    <key>percentCompleteNumber</key>
    <real>0.66666668653488159</real>
    <key>resume</key>
    <string></string>
    <key>shared</key>
    <false/>
</dict>
</plist>

Database structure

A 'database.db' file is associated to each series. It's a SQLite database that can be parsed by the sqlite3 tool.

sqlite3 database.db

Then

.tables .schema <table>

The database contains 3 tables:

  • 'card' table, which stores all card data
  • 'image' table, to store image entries/references data (not the actual image data)
  • 'card_image' to store associations between both tables above.

The 'card' Table

The 'card' table has the following columns:

  • identifier: a unique identifier for each card
  • cover_image_region_identifier: identifier for the image that represent the card
  • creation_date: card creation date.
  • modification_date: card modification date.
  • completed: whether the card is owned or not.
  • reference: A reference string.
  • A number of columns prefixed by 'Coll' that correspond to the ones listed in the series.plist file that correspond to user created fields in the series template (and their corresponding type).

The 'image' Table

The 'image' table has the following columns:

  • identifier: unique identifier
  • name: file name.

The 'card_image' Table

  • identifier: internal association id
  • card_identifier: references the card identifier in the card table
  • image_identifier: references the image identifier in the image table