hpsdecode

A Python library for decoding HPS (HIMSA Packed Scan) and DCM files used by dental and audiological scanning software such as 3Shape and ShapeDesigner.

HPS is a compressed 3D mesh format commonly used in dental scanning applications and other HIMSA-compliant devices.

Features

• Read mesh geometry (vertices and faces) from HPS files.
• Supports CA, CC, and CE schemas, including encrypted files.
• Extract mesh colors, texture coordinates (UVs) and texture images.
• Extract splines and curves in the scan data.
• Export the mesh to OBJ, PLY and STL.
• Command-line tool for exporting meshes.

Getting Started

Installation

pip install hpsdecode

Basic Usage

from hpsdecode import load_hps

# Load from file path
packed, mesh = load_hps("scan.dcm")

# Access mesh data
print(f"Vertices: {mesh.num_vertices}")
print(f"Faces: {mesh.num_faces}")
print(f"Schema: {packed.schema}")

# Vertex positions as (N, 3) float32 array
vertices = mesh.vertices

# Face indices as (M, 3) int32 array  
faces = mesh.faces

Compression Schemas

Schema	Status	Description
CA	✅ Supported	Identical to CC; provided for backward compatibility.
CB	❌ Not Planned	Lossy compression with optional color and texture data. No example data available.
CC	✅ Supported	Lossless compression with uncompressed vertices and compressed faces.
CE	✅ Supported	Encrypted version of CC. Requires an encryption key.

Encrypted Files (CE Schema)

Some HPS files use the CE schema, which encrypts the mesh data. To decode these files, you must provide the encryption key.

Note

This library does not provide encryption keys, nor will it provide instructions on how to obtain them.

Providing the Encryption Key

Option 1: Environment Variable (Recommended)

Set the HPS_ENCRYPTION_KEY environment variable before loading files:

export HPS_ENCRYPTION_KEY="28,141,16,74,219,32,11,126,55,178,97,3,41,82,213,222"

from hpsdecode import load_hps

# Automatically uses the key from the environment variable
packed, mesh = load_hps("encrypted.hps")

Option 2: Direct Key

Provide the key directly as a bytes object:

from hpsdecode import load_hps

key = bytes([28, 141, 16, 74, 219, 32, 11, 126, 55, 178, 97, 3, 41, 82, 213, 222])

packed, mesh = load_hps("encrypted.hps", encryption_key=key)

Option 3: Custom Key Provider

Implement your own key provider for advanced use cases (e.g., loading from a configuration file):

from hpsdecode import load_hps
from hpsdecode.encryption import EncryptionKeyProvider

class MyKeyProvider(EncryptionKeyProvider):
    def get_key(self, properties):
        return load_key_from_config()


key_provider = MyKeyProvider()
packed, mesh = load_hps("encrypted.hps", encryption_key=key_provider)

File Format Overview

HPS files are XML documents containing base64-encoded binary mesh data:

<HPS version="1.1">
    <Packed_geometry>
        <Schema>CA</Schema>
        <Binary_data>
            <CA version="1.0">
                <Vertices base64_encoded_bytes="..." vertex_count="...">
                    <!-- Base64-encoded float32 vertex positions -->
                </Vertices>
                <Facets base64_encoded_bytes="..." facet_count="...">
                    <!-- Base64-encoded face commands -->
                </Facets>
            </CA>
        </Binary_data>
    </Packed_geometry>
</HPS>

Command-Line Interface (CLI)

After installing, you can use the hpsdecode command to export meshes directly from HPS files.

Exporting Meshes

hpsdecode export input.hps output.obj

You can specify options such as export format (auto-detected by file extension), ASCII or binary mode, and whether to include/exclude colors or textures:

hpsdecode export input.hps output.ply --ascii --no-colors --no-textures

Encrypted HPS files (CE schema) require an encryption key.
You can supply it using --key or the HPS_ENCRYPTION_KEY environment variable:

hpsdecode export encrypted.hps output.obj --key "28,141,16,74,..."

Material Options

For OBJ export, you can provide material properties:

hpsdecode export input.hps output.obj \
  --ambient 0.5 0.5 0.5 --diffuse 0.8 0.8 0.8 \
  --specular 1.0 1.0 1.0 --shininess 20 --dissolve 1.0

Run hpsdecode export --help for a full list of CLI options.

Format Support

Format	Vertices & Faces	Vertex Colors	Textures	Binary/ASCII
OBJ	✅	✅*	✅	ASCII
PLY	✅	✅	✅**	ASCII/Binary
STL	✅	❌	❌	ASCII/Binary

^{* OBJ vertex colors use a non-standard extension; not all software supports this.
** PLY textures are baked into vertex colors. This may result in loss of quality.}

Example Scripts

• Inspect an HPS file:
  Print metadata, stats, and mesh extents to the console:

  python examples/inspect_hps.py path/to/file.hps

• View HPS file in 3D:
  Visualize the mesh in an interactive viewer (requires trimesh):

  python examples/view_hps.py path/to/file.hps

  Run pip install trimesh[recommend] for viewing support.

Contributing

Contributions, bug reports, and feature requests are welcome! Please open an issue or pull request if you would like to assist.

If you'd like to support development, consider donating to my Ko-fi page. Every contribution is highly appreciated!

License

This package is licensed under the MIT License. See the LICENSE file for more information.