cvsx2mvsx

cvsx2mvsx is a Python library and CLI tool designed to convert CVSX archives into MVSX or MVStory formats.

Installation

pip install cvsx2mvsx

CLI Usage

Convert a CVSX file to an MVSX archive:

uvx cvsx2mvsx --input examples/emd-1832.cvsx --output output.mvsx --format mvsx

Convert a CVSX file to the MVStory format:

uvx cvsx2mvsx --input examples/emd-1832.cvsx --output output.mvstory --format mvstory

Lattice to Mesh Conversion

If your input CVSX contains Lattice segmentations (voxel masks) and you wish to convert them to meshes via Marching Cubes rather than keeping them as volumes:

uvx cvsx2mvsx --input examples/emd-1832.cvsx --output output.mvsx --lattice-to-mesh

Arguments

Python API Usage

MVSX Pipeline

To create an MVSX file, you define a pipeline that extracts, transforms to the internal model, transforms to MVSX state, and loads to disk.

# 1. Declare the pipeline structure
pipeline = Pipeline([
    ExtractCVSX(),
    TransformToInternal(),
    TransformToMVSX(),
    LoadMVSX()
])

# 2. Define run configuration
config = PipelineConfig(
      input_path="path/to/input.cvsx",
      output_path="path/to/output.mvsx",
      lattice_to_mesh=True,
)

# 3. Execute
pipeline.run(config)

MVStory Pipeline

To create a Story, simply swap the transformation and loading steps of the MVSX pipeline:

pipeline = Pipeline([
    ExtractCVSX(),
    TransformToInternal(),
    TransformToMVStory(),
    LoadMVStory()
])

config = PipelineConfig(
      input_path="path/to/input.cvsx",
      output_path="path/to/output.mvstory",
      lattice_to_mesh=True,
)


pipeline.run(config)

Architecture

The library follows a ETL (Extract, Transform, Load) Pipeline pattern.

Core Concepts

1. Pipeline: A container that executes a list of steps sequentially. It manages the lifecycle of the process.
2. Context: A shared state object passed between steps. It manages configuration, holds a temporary working directory for intermediate files, and cleans up resources automatically after execution.
3. Steps: Discrete units of logic that implement a generic interface.

The Pipeline Flow

1. Extract (ExtractCVSX):
   • Unzips the .cvsx archive into the pipeline context temp directory.
   • Parses index.json, metadata, and BinaryCIF files using ciftools.
2. Transform (TransformToInternal):
   • Converts CVSX data into a normalized InternalEntry model.
   • Handles complex logic like Lattice-to-Mesh conversion (Marching Cubes).
3. Transform (TransformToMVSX / TransformToMVStory):
   • Converts the InternalEntry into format-specific representations (MVSX or MVStory).
4. Load (LoadMVSX / LoadMVStory):
   • Packages the processed assets and state into the final binary output file.