Invisible Watermark GPU

https://github.com/stability-ai/invisible-watermark-gpu
Admin
Invisible Watermark GPU is a Python library for creating invisible digital watermarks on images...
Tokens:44,589
Snippets:261
Trust Score:9.3
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install invisible-watermark-gpu with CUDA setup

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Set up environment variables for CUDA and install the package. Requires knowing your GPU's gencode (e.g., 80 for A100) and loading the appropriate CUDA version. Use --no-cache-dir to avoid caching issues.

```bash
# find your GPU's gencode here, and set the PYCUDWT_CC environment variable to it
# for example, for an A100, it would be "80" for SM80:
# https://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/ 
export PYCUDWT_CC=80

# also, load your CUDA version and set any and all needed environment variables. this might
# depend on your CUDA version + GPU type. I'm using CUDA 12.1 on an A100
module load cuda/12.1
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/cuda/lib64
export CUDA_PATH=/usr/local/cuda
export PYCUDWT_CC=80
export CUDAHOME=/usr/local/cuda-12.1

# install !
pip install invisible-watermark-gpu --no-cache-dir
```

--------------------------------

### CLI: invisible-watermark

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Command-line interface for embedding and decoding watermarks in images.

```APIDOC
## CLI: invisible-watermark

### Description
Command-line interface for embedding and decoding watermarks in images.

### Method
CLI command

### Endpoint
invisible-watermark [arguments] input

### Parameters
#### Positional Arguments
- **input** (str) - Required - The path of input image.

#### Optional Arguments
- **-h, --help** - Show help message and exit.
- **-a ACTION, --action ACTION** - encode|decode (default: None)
- **-t TYPE, --type TYPE** - bytes|b16|bits|uuid|ipv4 (default: bits)
- **-m METHOD, --method METHOD** - dwtDct|dwtDctSvd|rivaGan (default: maxDct)
- **-w WATERMARK, --watermark WATERMARK** - Embedded string (default: )
- **-l LENGTH, --length LENGTH** - Watermark bits length, required for bytes|b16|bits watermark (default: 0)
- **-o OUTPUT, --output OUTPUT** - The path of output (default: None)
- **-v, --verbose** - Print info (default: False)

### Request Example
```bash
# Embed watermark
./invisible-watermark -v -a encode -t bytes -m dwtDct -w 'hello' -o ./test_vectors/wm.png ./test_vectors/original.jpg

# Decode watermark
./invisible-watermark -v -a decode -t bytes -m dwtDct -l 40 ./test_vectors/wm.png
```

### Response
For encode, writes the watermarked image to the output path. For decode, prints the decoded watermark.
```

--------------------------------

### WatermarkEncoder.warmup_gpu

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Warms up the GPU to avoid cold start latency when encoding. Currently only supported for the 'dwtDct' method.

```APIDOC
## WatermarkEncoder.warmup_gpu

### Description
Warms up the GPU to avoid cold start latency when encoding. Currently only supported for the 'dwtDct' method.

### Method
Python method

### Endpoint
WatermarkEncoder.warmup_gpu()

### Parameters
None

### Request Example
```python
from imwatermark import WatermarkEncoder

WatermarkEncoder().warmup_gpu()
```

### Response
No return value.
```

--------------------------------

### Verify pycudwt installation with pytest

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Run this test to confirm the pycudwt package is correctly installed. Without passing, the package will silently output zeros and decoding will fail.

```bash
# without this test passing, your pycudwt package will NOT work properly, and it will
# only output zeros, silently causing you to not be able to decode anything!
python -m pytest -k 'test_pycudwt_installed_correctly'
```

--------------------------------

### Basic usage example

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Shows how to load an image, set a watermark, encode it with dwtDct, and save the result.

```python
import cv2
from imwatermark import WatermarkEncoder

bgr = cv2.imread('test.png')          # uint8, BGR
wm = 'test'

encoder = WatermarkEncoder()
encoder.set_watermark('bytes', wm.encode('utf-8'))
bgr_encoded = encoder.encode(bgr, 'dwtDct')

cv2.imwrite('test_wm.png', bgr_encoded)
```

--------------------------------

### Run pytest gate for pycudwt installation

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/configuration.md

Runs the pytest gate that checks the GPU install by verifying the pycudwt wavelet transform works correctly. The test asserts DWT approximation coefficients of random noise are non-zero and forward transform completes in < 40 ms.

```bash
python -m pytest -k 'test_pycudwt_installed_correctly'
```

--------------------------------

### Warm up GPU for WatermarkEncoder

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Warms up the GPU to avoid cold start problems when loading CUDA libraries. Only supported for the 'dwtDct' method currently. Run this before encoding images.

```python
from imwatermark import WatermarkEncoder

# only supported for method "dwtDct" currently
WatermarkEncoder().warmup_gpu()
```

--------------------------------

### Error handling example

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Demonstrates catching ValueError for small images and handling rivaGan requirements: model load and exactly 32 bits.

```python
import cv2
from imwatermark import WatermarkEncoder

bgr = cv2.imread('tiny.png')  # e.g. 100x100
enc = WatermarkEncoder()
enc.set_watermark('bits', [1, 0] * 16)

try:
    out = enc.encode(bgr, 'dwtDct')
except ValueError as e:
    print('image too small:', e)

# rivaGan requires a one-time model load and exactly 32 bits
enc.set_watermark('bits', [1] * 32)
try:
    from imwatermark import WatermarkEncoder as WE
    WE.loadModel()          # loads ONNX sessions (or raises ImportError)
    out = enc.encode(bgr, 'rivaGan')
except (RuntimeError, ImportError) as e:
    print('rivaGan unusable:', e)
```

--------------------------------

### CLI commands and arguments for invisible-watermark

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Shows the CLI usage for encoding and decoding watermarks, along with the positional and optional arguments. The encode command embeds a watermark, and the decode command extracts it. Options include action, type, method, watermark, length, output, and verbose.

```bash
embed watermark:  ./invisible-watermark -v -a encode -t bytes -m dwtDct -w 'hello' -o ./test_vectors/wm.png ./test_vectors/original.jpg

decode watermark: ./invisible-watermark -v -a decode -t bytes -m dwtDct -l 40 ./test_vectors/wm.png

positional arguments:
  input                 The path of input

optional arguments:
  -h, --help            show this help message and exit
  -a ACTION, --action ACTION
                        encode|decode (default: None)
  -t TYPE, --type TYPE  bytes|b16|bits|uuid|ipv4 (default: bits)
  -m METHOD, --method METHOD
                        dwtDct|dwtDctSvd|rivaGan (default: maxDct)
  -w WATERMARK, --watermark WATERMARK
                        embedded string (default: )
  -l LENGTH, --length LENGTH
                        watermark bits length, required for bytes|b16|bits
                        watermark (default: 0)
  -o OUTPUT, --output OUTPUT
                        The path of output (default: None)
  -v, --verbose         print info (default: False)
```

--------------------------------

### loadModel classmethod loads ONNX sessions

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/RivaWatermark.md

Loads both ONNX encoder and decoder sessions into class-level singletons. Idempotent; returns early if already loaded. Raises ImportError if onnxruntime is not installed. Must be called once before encode/decode with rivaGan.

```python
@classmethod
def loadModel(cls):
    try:
        import onnxruntime
    except ImportError:
        raise ImportError(
            "The `RivaWatermark` class requires onnxruntime to be installed. "
            "You can install it with pip: `pip install onnxruntime`."
        )

    if RivaWatermark.encoder and RivaWatermark.decoder:
        return
    modelDir = os.path.dirname(os.path.abspath(__file__))
    RivaWatermark.encoder = onnxruntime.InferenceSession(
        os.path.join(modelDir, 'rivagan_encoder.onnx'))
    RivaWatermark.decoder = onnxruntime.InferenceSession(
        os.path.join(modelDir, 'rivagan_decoder.onnx'))
```

--------------------------------

### WatermarkDecoder.decode

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Decodes a watermark from an image. The watermark type and bit length are specified in the constructor.

```APIDOC
## WatermarkDecoder.decode

### Description
Decodes a watermark from an image. The watermark type and bit length are specified in the constructor.

### Method
Python method

### Endpoint
WatermarkDecoder.decode(image, method)

### Parameters
- **image** (numpy.ndarray) - Required - The input image in BGR format.
- **method** (str) - Required - The watermarking method to use (e.g., 'dwtDct').

### Request Example
```python
import cv2
from imwatermark import WatermarkDecoder

bgr = cv2.imread('test_wm.png')

decoder = WatermarkDecoder('bytes', 32)
watermark = decoder.decode(bgr, 'dwtDct')
print(watermark.decode('utf-8'))
```

### Response
Returns the decoded watermark as bytes.
```

--------------------------------

### WatermarkEncoder.set_watermark

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Sets the watermark to be embedded. The watermark type and value are specified.

```APIDOC
## WatermarkEncoder.set_watermark

### Description
Sets the watermark to be embedded. The watermark type and value are specified.

### Method
Python method

### Endpoint
WatermarkEncoder.set_watermark(watermark_type, watermark)

### Parameters
- **watermark_type** (str) - Required - The type of watermark (e.g., 'bytes').
- **watermark** (bytes) - Required - The watermark value, typically encoded bytes.

### Request Example
```python
encoder.set_watermark('bytes', wm.encode('utf-8'))
```

### Response
No return value.
```

--------------------------------

### Embed watermark with WatermarkEncoder

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Embeds a 4-character (32-bit) watermark into an image using the 'dwtDct' method. Reads 'test.png', sets the watermark to 'test', encodes, and writes the result to 'test_wm.png'.

```python
import cv2
from imwatermark import WatermarkEncoder

bgr = cv2.imread('test.png')
wm = 'test'

encoder = WatermarkEncoder()
encoder.set_watermark('bytes', wm.encode('utf-8'))
bgr_encoded = encoder.encode(bgr, 'dwtDct')

cv2.imwrite('test_wm.png', bgr_encoded)
```

--------------------------------

### Decode watermark with WatermarkDecoder

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Decodes a 4-character (32-bit) watermark from an image using the 'dwtDct' method. Reads 'test_wm.png', decodes with a length of 32 bits, and prints the watermark string.

```python
import cv2
from imwatermark import WatermarkDecoder

bgr = cv2.imread('test_wm.png')

decoder = WatermarkDecoder('bytes', 32)
watermark = decoder.decode(bgr, 'dwtDct')
print(watermark.decode('utf-8'))
```

--------------------------------

### WatermarkEncoder.encode

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/README.md

Embeds a watermark into an image. The watermark is set using set_watermark and then encoded with the specified method.

```APIDOC
## WatermarkEncoder.encode

### Description
Embeds a watermark into an image. The watermark is set using set_watermark and then encoded with the specified method.

### Method
Python method

### Endpoint
WatermarkEncoder.encode(image, method)

### Parameters
- **image** (numpy.ndarray) - Required - The input image in BGR format.
- **method** (str) - Required - The watermarking method to use (e.g., 'dwtDct').

### Request Example
```python
import cv2
from imwatermark import WatermarkEncoder

bgr = cv2.imread('test.png')
wm = 'test'

encoder = WatermarkEncoder()
encoder.set_watermark('bytes', wm.encode('utf-8'))
bgr_encoded = encoder.encode(bgr, 'dwtDct')
```

### Response
Returns the watermarked image as a numpy.ndarray.
```

--------------------------------

### Encode with GPU method (dwtDct)

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/cli.md

Encode a text watermark into an image using the GPU method. Requires the `-o` output flag and `-w` watermark. The `PYCUDWT_CC` environment variable is only needed at install time; already-installed environments can skip it.

```bash
export PYCUDWT_CC=80   # install-time requirement only; already-installed envs skip this
invisible-watermark -v -a encode -t bytes -m dwtDct -w 'hello' -o ./wm.png ./original.jpg
```

--------------------------------

### EmbedMaxDct.__init__

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/configuration.md

Constructor for the EmbedMaxDct method implementation class. Initializes the DCT-based embedding method with configurable parameters.

```APIDOC
## EmbedMaxDct.__init__

### Description
Constructor for the EmbedMaxDct method implementation class. Initializes the DCT-based embedding method with configurable parameters.

### Method
Constructor

### Signature
`EmbedMaxDct.__init__(self, watermarks=[], wmLen=8, scales=[0, 36, 36], block=4)`

### Parameters
- `watermarks` (list[int]) - Optional - Bit sequence to embed; length may differ from `wmLen` (bits are cycled via `num % wmLen`). Default is `[]`.
- `wmLen` (int) - Optional - Number of watermark bits; drives score bucketing and modulo cycling during encoding. Default is `8`.
- `scales` (list[int] length 3) - Optional - Per YUV-channel embedding strength, indexes 0 and 1 only. Channels with `scales[channel] <= 0` are skipped. Default is `[0, 36, 36]`.
- `block` (int) - Optional - DCT block size. Frame is divided into `(row // block) x (col // block)` blocks. Default is `4`.

### Notes
- Constructor always instantiates `pycudwt.Wavelets` over a random 1024×1024 image to force-load CUDA libraries (GPU warmup side effect).
```

--------------------------------

### RivaWatermark.__init__

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/configuration.md

Constructor for the RivaWatermark method implementation class. Initializes the RivaGAN-based embedding method with configurable parameters.

```APIDOC
## RivaWatermark.__init__

### Description
Constructor for the RivaWatermark method implementation class. Initializes the RivaGAN-based embedding method with configurable parameters.

### Method
Constructor

### Signature
`RivaWatermark.__init__(self, watermarks=[], wmLen=32, threshold=0.52)`

### Parameters
- `watermarks` (list[int]) - Optional - Bit sequence to embed; length may differ from `wmLen` (bits are cycled via `num % wmLen`). Default is `[]`.
- `wmLen` (int) - Optional - Number of watermark bits; must be 32, otherwise raises `RuntimeError`. Default is `32`.
- `threshold` (float) - Optional - Decode decision threshold: bit is 1 when `data > threshold`. Default is `0.52`.

### Notes
- Rejects `wmLen != 32` with `RuntimeError`.
- Stores `_data` as float32 `(1, wmLen)` torch tensor.
```

--------------------------------

### Import WatermarkDecoder

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkDecoder.md

Import the public decode-side entry point from the package top level or from the defining module.

```python
from imwatermark import WatermarkDecoder
# alternative: from imwatermark.watermark import WatermarkDecoder
```

--------------------------------

### EmbedDwtDctSvd.__init__

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/configuration.md

Constructor for the EmbedDwtDctSvd method implementation class. Initializes the DWT-DCT-SVD based embedding method with configurable parameters.

```APIDOC
## EmbedDwtDctSvd.__init__

### Description
Constructor for the EmbedDwtDctSvd method implementation class. Initializes the DWT-DCT-SVD based embedding method with configurable parameters.

### Method
Constructor

### Signature
`EmbedDwtDctSvd.__init__(self, watermarks=[], wmLen=8, scales=[0,36,0], block=4)`

### Parameters
- `watermarks` (list[int]) - Optional - Bit sequence to embed; length may differ from `wmLen` (bits are cycled via `num % wmLen`). Default is `[]`.
- `wmLen` (int) - Optional - Number of watermark bits; drives score bucketing and modulo cycling during encoding. Default is `8`.
- `scales` (list[int] length 3) - Optional - Per YUV-channel embedding strength, indexes 0 and 1 only. Channels with `scales[channel] <= 0` are skipped. Default is `[0,36,0]`.
- `block` (int) - Optional - DCT block size. Frame is divided into `(row // block) x (col // block)` blocks. Default is `4`.

### Notes
- Pure NumPy/PyWavelets; no warmup side effect.
```

--------------------------------

### Direct construction with non-default config

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/EmbedDwtDctSvd.md

Shows how to directly instantiate EmbedDwtDctSvd with custom parameters and use its encode and decode methods.

```APIDOC
## Direct construction with non-default config

### Description
Demonstrates direct instantiation of `EmbedDwtDctSvd` with custom watermarks, length, scales, and block size, then encoding and decoding an image.

### Example
```python
from imwatermark.dwtDctSvd import EmbedDwtDctSvd

wm_bits = [1, 0, 1, 1, 0, 0, 1, 1]
emb = EmbedDwtDctSvd(watermarks=wm_bits, wmLen=8, scales=[0, 72, 36], block=4)
out = emb.encode(cv2.imread('test.png'))
print(emb.decode(out))
```
```

--------------------------------

### WatermarkEncoder.__init__

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Creates a new WatermarkEncoder instance. The optional content parameter initializes the watermark payload, which is expanded to bits.

```APIDOC
## WatermarkEncoder.__init__

### Description
Creates a new WatermarkEncoder instance. The optional content parameter initializes the watermark payload, which is expanded to bits.

### Method
Constructor

### Signature
```python
def __init__(self, content=b""):
```

### Parameters
- **content** (bytes-like iterable of int) - Optional - Initial watermark; each byte is expanded to 8 bits via `np.unpackbits`.

### Returns
An encoder with `_wmType = "bytes"`. With the default `content`, `_wmLen == 0`, which is only useful for GPU warmup.

```

--------------------------------

### Error handling (missing dependency / missing load)

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/RivaWatermark.md

Shows how to handle errors when the onnxruntime dependency is missing or when the model has not been loaded before encoding.

```python
import cv2
from imwatermark import WatermarkEncoder

enc = WatermarkEncoder()
enc.set_watermark('bits', [1] * 32)

try:
    WatermarkEncoder.loadModel()        # ImportError if onnxruntime missing
except ImportError as e:
    print('onnxruntime required for rivaGan:', e)

try:
    out = enc.encode(cv2.imread('test.png'), 'rivaGan')
except RuntimeError as e:
    print('model not loaded:', e)       # raised by RivaWatermark.encode/decode

try:
    enc.set_watermark('bits', [1] * 16)  # 16 != 32
    out = enc.encode(cv2.imread('test.png'), 'rivaGan')
except RuntimeError as e:
    print('bit length:', e)             # 'rivaGan only supports 32 bits watermarks now.'

```

--------------------------------

### WatermarkEncoder.__init__

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/configuration.md

Constructor for the WatermarkEncoder class. Initializes the encoder with an optional initial watermark payload.

```APIDOC
## WatermarkEncoder.__init__

### Description
Constructor for the WatermarkEncoder class. Initializes the encoder with an optional initial watermark payload.

### Method
Constructor

### Signature
`WatermarkEncoder.__init__(self, content=b"")`

### Parameters
- `content` (bytes-like) - Optional - Initial watermark payload; each byte is `np.unpackbits`-expanded into 8 bits. Default is `b""`.

### Notes
- A fresh `WatermarkEncoder()` has `_wmLen == 0`; calling `encode` on it is only meaningful for GPU warmup, not for producing a real watermark.
```

--------------------------------

### Advanced dwtDct encoding with custom scales and block size

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/configuration.md

Use this example to embed a watermark with a custom strength into a single channel and a block size of 8. The `scales` list overrides the default `[0, 36, 36]` for `dwtDct`, and `block` sets the block size. Requires a BGR image loaded with OpenCV.

```python
import cv2
from imwatermark import WatermarkEncoder

bgr = cv2.imread("test.png")
enc = WatermarkEncoder()
enc.set_by_bits([1, 0, 1, 0, 1, 0, 1, 0])

# embed with custom strength into a single channel, block size 8
out = enc.encode(bgr, "dwtDct", scales=[0, 72, 0], block=8)
```

--------------------------------

### Basic usage of warmup_gpu()

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Shows how to call warmup_gpu() on a WatermarkEncoder instance. The first call takes ~2s for CUDA load, subsequent encodes take ~50ms.

```python
from imwatermark import WatermarkEncoder

WatermarkEncoder().warmup_gpu()  # one-time CUDA load; ~2s first time, then ~50ms encodes
```

--------------------------------

### WatermarkDecoder.__init__

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/configuration.md

Constructor for the WatermarkDecoder class. Initializes the decoder with the watermark type and expected bit length.

```APIDOC
## WatermarkDecoder.__init__

### Description
Constructor for the WatermarkDecoder class. Initializes the decoder with the watermark type and expected bit length.

### Method
Constructor

### Signature
`WatermarkDecoder.__init__(self, wm_type="bytes", length=0)`

### Parameters
- `wm_type` (str) - Optional - One of `bytes`, `b16`, `bits`, `uuid`, `ipv4`. Determines return format of `decode` and expected bit length rule. Default is `"bytes"`.
- `length` (int) - Required for `bytes`/`b16`/`bits`, ignored for `uuid`/`ipv4` - Expected watermark bit length. `ipv4` forces `_wmLen = 32`; `uuid` forces `_wmLen = 128`. For other types `_wmLen = length`. Passing mismatched `length` for `rivaGan` (must be 32) raises `RuntimeError`. Default is `0`.
```

--------------------------------

### Usage through the public API

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/RivaWatermark.md

Demonstrates how to use the RivaWatermark functionality through the public API, including loading the model, encoding a watermark, and decoding it.

```python
import cv2
from imwatermark import WatermarkEncoder, WatermarkDecoder

# 32 bits required
bits = [int(b) for b in f"{0b1011001111101100:016b}"] * 2   # 32 bits

WatermarkEncoder.loadModel()            # == RivaWatermark.loadModel(), one-time

enc = WatermarkEncoder()
enc.set_watermark('bits', bits)
bgr_encoded = enc.encode(cv2.imread('test.png'), 'rivaGan')

dec = WatermarkDecoder('bits', 32)      # wmLen must be 32 for rivaGan
out = dec.decode(bgr_encoded, 'rivaGan')
print(out)

```

--------------------------------

### EmbedMaxDct constructor with GPU warmup

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/EmbedMaxDct.md

Initializes the DWT+DCT embedder. Always constructs a pycudwt.Wavelets over a random 1024x1024 uint8 image to force CUDA library loading, warming the GPU for the entire Python process. Throws nothing explicitly; CUDA/pycudwt build errors surface here.

```python
def __init__(self, watermarks=[], wmLen=8, scales=[0, 36, 36], block=4):
    self._watermarks = watermarks
    self._wmLen = wmLen
    self._scales = scales
    self._block = block

    # Create a wavelets instance - this is just to "warmup" the GPU by loading cuda libraries.
    # Note: calling it in just this instance of EmbedMaxDct will warmup for all future instances
    # of EmbedMaxDct in same Python process!
    Wavelets(
        np.random.randint(low=0, high=255, size=(1024, 1024), dtype=np.uint8),
        "haar",
        1,
    )
```

--------------------------------

### warmup_gpu() method definition

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Defines the warmup_gpu method. Returns None and logs 'GPU warmup completed in {:.2f} ms' via the imwatermark logger. Call before a batch of encodes to pay the one-time cuLibraryLoadData / CUDA library load cost (~seconds) once.

```python
def warmup_gpu(self):
```

--------------------------------

### Direct construction of EmbedMaxDct with default configs

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/EmbedMaxDct.md

Directly instantiate the internal EmbedMaxDct class with default configurations (scales=[0, 36, 36], block=4) to encode and decode a watermark. Requires an input image 'test.png' and a watermark bit list of length 8.

```python
from imwatermark.maxDct import EmbedMaxDct
emb = EmbedMaxDct(watermarks=[1, 0] * 4, wmLen=8, scales=[0, 36, 36], block=4)
wm_bgr = emb.encode(cv2.imread('test.png'))
print(emb.decode(wm_bgr))
```

--------------------------------

### set_watermark method implementation

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Dispatches to the matching set_by_* method based on wmType. Raises NameError for unsupported wmType.

```python
def set_watermark(self, wmType="bytes", content=""):
    if wmType == "ipv4":
        self.set_by_ipv4(content)
    elif wmType == "uuid":
        self.set_by_uuid(content)
    elif wmType == "bits":
        self.set_by_bits(content)
    elif wmType == "bytes":
        self.set_by_bytes(content)
    elif wmType == "b16":
        self.set_by_b16(content)
    else:
        raise NameError("%s is not supported" % wmType)
```

--------------------------------

### warmup_gpu()

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Performs a one-time CUDA library load to warm up the GPU before batch encoding. Call this before a batch of encodes to avoid the initial ~2 second load cost.

```APIDOC
## warmup_gpu()

### Description
Performs a one-time CUDA library load to warm up the GPU before batch encoding. Call this before a batch of encodes to avoid the initial ~2 second load cost.

### Method
warmup_gpu()

### Parameters
None

### Returns
None. Logs "GPU warmup completed in {:.2f} ms" via the `imwatermark` logger.

### Usage Example
```python
from imwatermark import WatermarkEncoder

WatermarkEncoder().warmup_gpu()  # one-time CUDA load; ~2s first time, then ~50ms encodes
```
```

--------------------------------

### WatermarkDecoder.__init__

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkDecoder.md

Constructor for the WatermarkDecoder class. Initializes the decoder with the specified watermark type and expected bit length, fixing the reconstruction format and bit length.

```APIDOC
## WatermarkDecoder.__init__

### Description
Constructor for the WatermarkDecoder class. Initializes the decoder with the specified watermark type and expected bit length, fixing the reconstruction format and bit length.

### Method
Constructor

### Signature
```python
def __init__(self, wm_type="bytes", length=0):
```

### Parameters
- **wm_type** (str) - Optional, default `"bytes"` - One of `ipv4`, `uuid`, `bytes`, `bits`, `b16`. Anything else raises `NameError`.
- **length** (int) - Required for `bytes`/`b16`/`bits`, default `0` - Expected watermark bit length; ignored for `ipv4` (32) and `uuid` (128).

### Throws
- `NameError` for unsupported `wm_type`.
- For `rivaGan` decoding, `length` must be `32`, otherwise the eventual `RivaWatermark(...)` construction raises `RuntimeError`.

### Example
```python
from imwatermark import WatermarkDecoder

decoder = WatermarkDecoder(wm_type="bytes", length=32)
```
```

--------------------------------

### Import RivaWatermark class

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/RivaWatermark.md

Import path for the internal RivaWatermark class, used internally by WatermarkEncoder/Decoder when method='rivaGan'.

```python
from imwatermark.rivaGan import RivaWatermark
```

--------------------------------

### WatermarkEncoder constructor

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Constructor for WatermarkEncoder. Accepts optional initial watermark content as bytes-like iterable of int; each byte is expanded to 8 bits via np.unpackbits. Default content b"" results in _wmLen == 0, useful only for GPU warmup.

```python
def __init__(self, content=b""):
```

--------------------------------

### loadModel() — classmethod

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/RivaWatermark.md

Loads the ONNX encoder and decoder sessions into class-level singletons. Must be called once before using encode/decode with rivaGan.

```APIDOC
## loadModel() — classmethod

### Description
Loads both ONNX sessions from the package directory into the class-level singleton, unless already loaded (idempotent). Must be called once before any `encode`/`decode` with `rivaGan`.

### Method
classmethod

### Parameters
None

### Returns
`None`

### Throws
- `ImportError` when `onnxruntime` is unavailable.

### Access
Accessible via the public API as `WatermarkEncoder.loadModel()`.
```

--------------------------------

### Encode and decode watermark via CLI

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/cli.md

Use the invisible-watermark CLI to encode a watermark into an image and decode it. The encode command requires -a encode, -m dwtDct, -w with the watermark string, and -o for output. The decode command requires -a decode, -m dwtDct, and -l 40 for the watermark length. Note: the default -m maxDct is invalid and raises NameError; always pass -m dwtDct.

```bash
invisible-watermark -v -a encode -t bytes -m dwtDct -w 'hello' -o ./wm.png ./original.jpg
```

```bash
invisible-watermark -v -a decode -t bytes -m dwtDct -l 40 ./wm.png
```

--------------------------------

### Direct construction with non-default config

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/EmbedDwtDctSvd.md

Shows how to use EmbedDwtDctSvd directly with custom watermarks, length, scales, and block size. The encode method returns the watermarked image, and decode retrieves the watermark bits.

```python
from imwatermark.dwtDctSvd import EmbedDwtDctSvd

wm_bits = [1, 0, 1, 1, 0, 0, 1, 1]
emb = EmbedDwtDctSvd(watermarks=wm_bits, wmLen=8, scales=[0, 72, 36], block=4)
out = emb.encode(cv2.imread('test.png'))
print(emb.decode(out))
```

--------------------------------

### Error handling for missing onnxruntime and model load

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/RivaWatermark.md

Demonstrates catching ImportError when onnxruntime is missing during loadModel, RuntimeError when encoding without a loaded model, and RuntimeError when the watermark bit length is not 32. The last error message is 'rivaGan only supports 32 bits watermarks now.'

```python
import cv2
from imwatermark import WatermarkEncoder

enc = WatermarkEncoder()
enc.set_watermark('bits', [1] * 32)

try:
    WatermarkEncoder.loadModel()        # ImportError if onnxruntime missing
except ImportError as e:
    print('onnxruntime required for rivaGan:', e)

try:
    out = enc.encode(cv2.imread('test.png'), 'rivaGan')
except RuntimeError as e:
    print('model not loaded:', e)       # raised by RivaWatermark.encode/decode

try:
    enc.set_watermark('bits', [1] * 16)  # 16 != 32
    out = enc.encode(cv2.imread('test.png'), 'rivaGan')
except RuntimeError as e:
    print('bit length:', e)             # 'rivaGan only supports 32 bits watermarks now.'
```

--------------------------------

### Import WatermarkEncoder

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Import the WatermarkEncoder class from the package top level or from the watermark module.

```python
from imwatermark import WatermarkEncoder
# alternative: from imwatermark.watermark import WatermarkEncoder
```

--------------------------------

### RivaWatermark constructor

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/RivaWatermark.md

Constructor for RivaWatermark. Requires wmLen=32, otherwise raises RuntimeError. Stores watermarks as float32 tensor.

```python
def __init__(self, watermarks=[], wmLen=32, threshold=0.52):
    self._watermarks = watermarks
    self._threshold = threshold
    if wmLen not in [32]:
        raise RuntimeError('rivaGan only supports 32 bits watermarks now.')
    self._data = torch.from_numpy(np.array([self._watermarks], dtype=np.float32))
```

--------------------------------

### Error handling: missing output and missing length

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/cli.md

Shows exit codes and stderr messages for common errors. Missing `-o` on encode exits with code 1 and prints "output is required. exiting...". Missing `-l` on decode of `bytes` type exits with code 1 and prints "length is required for bytes watermark decoding".

```bash
# capture exit code + stderr; note the -m maxDct default is unusable
invisible-watermark -a encode -t bytes -m dwtDct -w hi ./original.jpg
# exit 1, stderr: "output is required. exiting..."

invisible-watermark -a decode -t bits -m dwtDct ./wm.png
# exit 1, stderr: "length is required for bytes watermark decoding"
```

--------------------------------

### Public API usage for encoding and decoding with rivaGan

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/RivaWatermark.md

Shows the full workflow: load the model once, set 32 bits, encode a BGR image with 'rivaGan', then decode with a WatermarkDecoder of length 32. The bits list is built from a 16-bit binary string repeated twice to reach 32 bits.

```python
import cv2
from imwatermark import WatermarkEncoder, WatermarkDecoder

# 32 bits required
bits = [int(b) for b in f"{0b1011001111101100:016b}"] * 2   # 32 bits

WatermarkEncoder.loadModel()            # == RivaWatermark.loadModel(), one-time

enc = WatermarkEncoder()
enc.set_watermark('bits', bits)
bgr_encoded = enc.encode(cv2.imread('test.png'), 'rivaGan')

dec = WatermarkDecoder('bits', 32)      # wmLen must be 32 for rivaGan
out = dec.decode(bgr_encoded, 'rivaGan')
print(out)
```

--------------------------------

### WatermarkDecoder constructor

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkDecoder.md

Constructor fixes the expected bit length and reconstruction format. Unsupported wm_type raises NameError. For rivaGan decoding, length must be 32.

```python
def __init__(self, wm_type="bytes", length=0):
    self._wmType = wm_type
    if wm_type == "ipv4":
        self._wmLen = 32
    elif wm_type == "uuid":
        self._wmLen = 128
    elif wm_type == "bytes":
        self._wmLen = length
    elif wm_type == "bits":
        self._wmLen = length
    elif wm_type == "b16":
        self._wmLen = length
    else:
        raise NameError("%s is unsupported" % wm_type)
```

--------------------------------

### invisible-watermark CLI

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/README.md

Command-line tool for embedding and extracting watermarks. It supports various watermark types and methods.

```APIDOC
## invisible-watermark CLI

### Description
Command-line tool for embedding and extracting watermarks. It supports various watermark types and methods.

### Usage
```
invisible-watermark [options] <input_image> <output_image>
```

### Options
- `--method` (string) - Watermark method: `dwtDct` (default), `dwtDctSvd`, `rivaGan`.
- `--wm-type` (string) - Watermark type: `bytes`, `b16`, `bits`, `uuid`, `ipv4`.
- `--wm-content` (string) - Watermark content (e.g., text for `bytes`, hex for `b16`, comma-separated bits for `bits`, UUID string, IPv4 address).
- `--decode` - Flag to extract watermark instead of embedding.
- `--wm-length` (int) - Required for decoding; length of watermark in bits.

### Examples
Embed a watermark:
```
invisible-watermark --method dwtDct --wm-type bytes --wm-content "my watermark" input.png output.png
```

Extract a watermark:
```
invisible-watermark --decode --method dwtDct --wm-type bytes --wm-length 88 input.png
```
```

--------------------------------

### Encode and decode raw bits

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/cli.md

Encode and decode a raw bit string watermark. The length `-l` must match the number of bits in the watermark.

```bash
invisible-watermark -a encode -t bits -m dwtDct -w '1011001' -o ./wm.png ./original.jpg
invisible-watermark -a decode -t bits -m dwtDct -l 7 ./wm.png
```

--------------------------------

### EmbedDwtDctSvd constructor

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/EmbedDwtDctSvd.md

Constructor with default parameters. Default scales [0,36,0] embeds only the U channel. No side effects in constructor.

```python
def __init__(self, watermarks=[], wmLen=8, scales=[0,36,0], block=4):
    self._watermarks = watermarks
    self._wmLen = wmLen
    self._scales = scales
    self._block = block
```

--------------------------------

### Error handling and per-method decode

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkDecoder.md

Demonstrates decoding with different watermark types and methods, including passing configs like scales. Catches ValueError for image/bit mismatches and NameError for bad types or methods.

```python
import cv2
from imwatermark import WatermarkDecoder, WatermarkEncoder
from imwatermark import WatermarkDecoder as WD

try:
    dec = WD('bits', 32)
    bits = dec.decode(cv2.imread('wm.png'), 'dwtDctSvd', scales=[0, 36, 0])
    print('bits:', bits)

    dec_ipv4 = WD('ipv4')               # length auto-set to 32
    print('ip:', dec_ipv4.decode(cv2.imread('wm_ip.png'), 'dwtDct'))
except ValueError as e:
    print('image/bit mismatch:', e)
except NameError as e:
    print('bad type/method:', e)
```

--------------------------------

### Import EmbedDwtDctSvd

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/EmbedDwtDctSvd.md

Import path for the internal class. Not re-exported at package top level; instantiated internally by WatermarkEncoder/Decoder when method='dwtDctSvd'.

```python
from imwatermark.dwtDctSvd import EmbedDwtDctSvd
```

--------------------------------

### set_by_bits method

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Sets watermark bits from an iterable of integers. Each element is reduced mod 2 and stored in _watermarks, with _wmLen set to the number of bits. When used with the rivaGan method, exactly 32 bits are required, otherwise a RuntimeError occurs.

```python
def set_by_bits(self, bits=[]):
    self._watermarks = [int(bit) % 2 for bit in bits]
    self._wmLen = len(self._watermarks)
    self._wmType = "bits"
```

--------------------------------

### Error handling for small images

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/EmbedDwtDctSvd.md

Demonstrates catching a ValueError when the image is too small (r*c < 256*256) during encode with the 'dwtDctSvd' algorithm.

```python
import cv2
from imwatermark import WatermarkEncoder

enc = WatermarkEncoder()
enc.set_by_bits([1] * 16)
try:
    # r*c < 256*256 raises inside encode() before any embedding
    out = enc.encode(cv2.imread('small.png'), 'dwtDctSvd')
except ValueError as e:
    print('image too small:', e)
```

--------------------------------

### WatermarkEncoder.loadModel

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Class method that loads the RivaGAN ONNX encoder/decoder sessions. Must be called once before using the 'rivaGan' method.

```APIDOC
## WatermarkEncoder.loadModel

### Description
Class method that loads the RivaGAN ONNX encoder/decoder sessions. Must be called once before using the 'rivaGan' method.

### Method
Classmethod

### Signature
```python
@classmethod
def loadModel(cls):
```

### Parameters
None

### Returns
None

### Exceptions
- Raises `ImportError` if `onnxruntime` is not installed.

```

--------------------------------

### Error handling

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/EmbedDwtDctSvd.md

Shows how to handle errors when the image is too small for the watermarking algorithm.

```APIDOC
## Error handling

### Description
Demonstrates catching a `ValueError` when the image dimensions are too small for the 'dwtDctSvd' algorithm.

### Example
```python
import cv2
from imwatermark import WatermarkEncoder

enc = WatermarkEncoder()
enc.set_by_bits([1] * 16)
try:
    # r*c < 256*256 raises inside encode() before any embedding
    out = enc.encode(cv2.imread('small.png'), 'dwtDctSvd')
except ValueError as e:
    print('image too small:', e)
```
```

--------------------------------

### WatermarkEncoder and WatermarkDecoder usage

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/EmbedDwtDctSvd.md

Shows how to use the public API to encode and decode watermarks with the 'dwtDctSvd' algorithm.

```APIDOC
## Usage through the public API

### Description
Demonstrates encoding and decoding watermarks using the `WatermarkEncoder` and `WatermarkDecoder` classes with the 'dwtDctSvd' algorithm.

### Example
```python
import cv2
from imwatermark import WatermarkEncoder, WatermarkDecoder

enc = WatermarkEncoder()
enc.set_by_bytes(b'hello')                      # 40 bits
bgr_encoded = enc.encode(cv2.imread('test.png'), 'dwtDctSvd')

dec = WatermarkDecoder('bytes', 40)
wm = dec.decode(bgr_encoded, 'dwtDctSvd')
print(wm.decode('utf-8'))
```
```

--------------------------------

### set_by_bytes method

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Sets watermark bits from a bytes-like payload. Converts each byte to 8 bits via np.unpackbits, storing them in _watermarks and setting _wmLen to 8 * len(content). Returns None.

```python
def set_by_bytes(self, content):
    self._wmType = "bytes"
    seq = np.array([n for n in content], dtype=np.uint8)
    self._watermarks = list(np.unpackbits(seq))
    self._wmLen = len(self._watermarks)
```

--------------------------------

### set_by_b16 method

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkEncoder.md

Sets watermark bits from a Base16 (hex) string. Decodes the string with base64.b16decode, then delegates to set_by_bytes. Sets _wmType to "b16". Raises binascii.Error for invalid hex.

```python
def set_by_b16(self, b16):
    content = base64.b16decode(b16)
    self.set_by_bytes(content)
    self._wmType = "b16"
```

--------------------------------

### Basic usage of WatermarkDecoder

Source: https://github.com/stability-ai/invisible-watermark-gpu/blob/main/_autodocs/api-reference/WatermarkDecoder.md

Shows how to create a decoder for 'bytes' type with length 32 (4 characters) and decode a watermarked image using the default 'dwtDct' method. The result is printed as UTF-8 text.

```python
import cv2
from imwatermark import WatermarkDecoder

bgr = cv2.imread('test_wm.png')

decoder = WatermarkDecoder('bytes', 32)   # 4 characters
watermark = decoder.decode(bgr, 'dwtDct')
print(watermark.decode('utf-8'))
```
Tokens:
Raw