Advanced Usage
This page describes deployment options, request parameters, and runtime behavior for the 3D Body Pose NIM.
The launch commands on this page read NGC_API_KEY from your shell and pull the image from nvcr.io. Export the key and log in with docker login nvcr.io first, as described in Getting Started.
Model Caching
On first launch, the container downloads the required models from NGC (about 3.5 GB). Mount a host directory as a cache to avoid re-downloading on subsequent runs.
Create the cache directory on the host before the first docker run:
Run the container with the cache directory mounted in the appropriate location:
LOCAL_NIM_CACHE can be any directory you own. If the log reports that the model download target is not writable, the directory most likely belongs to another user, typically root because Docker created it on an earlier run; change the block’s first line to a directory directly under your home, for example export LOCAL_NIM_CACHE=~/nim-cache, and run the block again. The container runs as uid 1000, so the directory needs a+rwX, and the files it downloads belong to uid 1000.
To pin the profile that is downloaded and loaded, set NIM_MODEL_PROFILE. For more information, refer to Model Manifest Profiles.
SSL Enablement
3D Body Pose NIM provides an SSL mode to ensure secure communication between clients and the server by encrypting data in transit. To enable SSL, you must provide the path to the SSL certificate and key files in the container. The following example shows how to do this:
The container expects a CA certificate, a server certificate signed by it, and the matching server key. mtls mode also needs a client certificate signed by the same CA. To generate a self-signed set for local testing, in an empty directory:
This block is POSIX shell, so it runs under sh/dash as well as bash and zsh. It leaves a few scratch files next to the certificates — san.cnf, the two CSRs (server.csr, client.csr), and the CA serial (ssl_ca_cert.srl).
SSL_CERT must be an absolute path. Docker reads a relative -v source as the name of a volume rather than a directory, so a relative value silently creates an empty named volume, mounts it over /opt/nim/crt, and the server then exits reporting that it cannot find a certificate you just generated.
NIM_SSL_MODE can be set to mtls, tls, or disabled. If set to mtls, the container uses mutual TLS authentication. If set to tls, the container uses TLS authentication.
For more information, refer to Environment Variables.
Verify the permissions of the SSL certificate and key files on the host machine. The container runs as uid 1000 and cannot start if the files are not readable by that user, for example a key that openssl wrote with mode 600. Grant read access to uid 1000 only, with setfacl -m u:1000:r ssl_key_server.pem, rather than making the private key world-readable. The server certificate must carry a Subject Alternative Name for the hostname that clients connect to.
NIM_SSL_MODE secures the gRPC port (8001) only. The HTTP endpoints on port 8000 stay plaintext.
To connect the sample Python client to an SSL-enabled server, set --ssl-mode to match NIM_SSL_MODE. Pass --ssl-root-cert for TLS or MTLS, and additionally --ssl-cert and --ssl-key for MTLS. Run the client from its scripts folder, with the virtual environment from Basic Inference active. The launch commands above export SSL_CERT, so the first line below keeps that value in the same shell. In a new shell, first run export SSL_CERT="{absolute path of the certs directory the recipe created}"; otherwise the first line stops with a message naming SSL_CERT:
A client whose --ssl-mode does not match the server fails to connect with UNAVAILABLE, for example a plaintext client against a tls or mtls server, or --ssl-mode TLS against an mtls server.
Multiple Concurrent Inputs
To enable multi-stream concurrent inference, set NV_AI4M_MAX_CONCURRENCY_PER_GPU to an integer greater than 1 on the server container.
Because Triton distributes the workload equally across all GPUs, the total number of concurrent inputs supported by the server is the number of GPUs multiplied by NV_AI4M_MAX_CONCURRENCY_PER_GPU.
A request that arrives when every slot is busy waits up to BODY_POSE_REQUEST_ADMISSION_TIMEOUT_SEC (default 15 seconds) for a slot, then fails with RESOURCE_EXHAUSTED. The wait is silent: the server takes the slot before it reads the first message off the stream, so nothing you sent was consumed.
The status detail names the two numbers that decide the outcome:
Retrying immediately against an unchanged server fails identically, so treat this as a capacity decision rather than a transient error: either serialise your streams, or raise NV_AI4M_MAX_CONCURRENCY_PER_GPU and restart the container.
Raising the concurrency lets several streams run at once but does not add throughput: on a saturated GPU, the aggregate frame rate is nearly flat from one stream to eight, so the same total is divided into more, slower streams. Refer to Concurrency. The GPU’s concurrent NVDEC session limit also bounds the number of concurrent inputs; refer to Unsupported Architectures.
Focal Length
The focal_length field in the BodyPoseConfig proto sets the pinhole focal length, in pixels, that the model uses, where fx equals fy.
- If the field is unset or set to
0, the NIM uses the SDK default derived from the image size. - Supplying the true focal length of the capture camera improves the metric accuracy of
keypoints_3d.
To set the focal length, include the field in the BodyPoseConfig message sent as the first request in the gRPC stream. Run the following from the client package root (nim-clients/body-pose/), where the relative interfaces path resolves, with the virtual environment from Basic Inference active:
With the sample client, use the --focal-length argument. Run it from the client’s scripts folder, with the same virtual environment active:
Contact Correction
The enable_contact field in the BodyPoseConfig proto turns on static-camera contact correction, which runs inverse kinematics to keep the body in contact with the ground plane. It is intended for a fixed camera with the subject standing or walking on a consistent ground plane, and it costs some throughput.
Contact correction is a server setting, fixed at startup: it is off unless the container is started with BODY_POSE_ENABLE_CONTACT=1. A request whose enable_contact value differs from the server’s is processed with the server’s value, and the response carries a warning in its initial metadata, which the sample client prints as Server warning:. Run one server per setting if you need both.
To start a server with contact correction on:
With the sample client, request contact correction with the --enable-contact argument, or turn it off with --no-enable-contact; omit both to accept the server’s value. Run it from the client’s scripts folder, with the virtual environment from Basic Inference active:
Confirming Which Value the Server Runs With
Contact correction only changes the output when a person is in frame, so a clip without one looks identical either way. Read the value off the server instead of inferring it from the output. The server logs it once, after the warmup inference latches it:
The grep below returns that line. With NIM_ENABLE_OTEL=1, the text is the body of an OpenTelemetry log record, so the grep returns the JSON line "body": "enable_contact startup latch done: ..." instead. loaded=True means contact correction is on for every stream this server serves; loaded=False means it is off. Nothing changes the value afterwards.
Service Information in the Response
Each response stream opens with a one-shot ServiceInfo message on the service_info field of BodyPoseResponse, before any pose result. It reports feature_name, feature_version, model_info, server_request_id, and client_session_id.
Quote server_request_id when reporting an issue; the log lines the pose pipeline writes for the stream carry it as a [GUID=<id>] prefix (a few decoder-lifecycle lines, such as GstVideoReader opened and End-Of-Stream reached., are written without it). In the following snippet, response_iterator is the response stream returned by BodyPoseServiceStub.EstimateBodyPose():
client_session_id echoes the value that the client sent in the client-session-id gRPC metadata header, and is empty when the client sends none. The sample client sets it from --client-session-id.
Advanced Tuning Variables
These variables tune internal timeouts and buffer sizes. The defaults suit every workload described in Performance Results. Change them only to address a specific problem.