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.

pip install hpsdecode

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

Some HPS files use the CE schema, which encrypts the mesh data. To decode these files, you must provide 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)

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>

• 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.

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!

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