Kiuikit

https://kit.kiui.moe
Admin
Kiuikit is a Python toolkit for computer vision and 3D vision tasks, providing utilities for meshes,...
Tokens:32,707
Snippets:246
Trust Score:6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install torch_scatter and run kiui.cli.remesh

Source: https://kit.kiui.moe/_sources/remesh.md.txt

Install the required torch_scatter package and run the remesh CLI. The example command processes chest.glb with 1000 iterations.

```bash
# install torch_scatter following https://github.com/rusty1s/pytorch_scatter
# e.g., for torch2.1.0+cu121
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.1.0+cu121.html

# help
python -m kiui.cli.remesh --help

# example
python -m kiui.cli.remesh --mesh chest.glb --iters 1000
```

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

### Rendering examples with kire

Source: https://kit.kiui.moe/render

Example commands for opening a GUI, setting resolution, specifying front direction, using PBR, and headless rendering. Includes options like --force_cuda_rast, --H, --W, --ssaa, --front_dir, --pbr, --envmap, --save_video, --save, and --wogui.

```bash
## open a GUI to render a mesh
kire mesh.obj
kire mesh.obj --force_cuda_rast # if you cannot use OpenGL backend (usually happens for headless servers), this will fallback to CUDA backend with some limitations (ref: https://nvlabs.github.io/nvdiffrast/#rasterizing-with-cuda-vs-opengl-new)
kire mesh.obj --H 800 --W 800 --ssaa 2 # set resolution and use super-sampling anti-aliasing

kire mesh.obj --front_dir +x # specify mesh front-facing dir, default is +z (OpenGL convention). You can use [+-][xyz] to specify axis, and [123] to specify clockwise rotation (per 90 degree).

kire mesh.glb --pbr # render with PBR (metallic + roughness)
kire mesh.glb --pbr --envmap env.hdr # specify hdr file

## we can also run without GUI on headless servers
kire mesh.obj --save_video out.mp4 --wogui # save 360 degree rotating video
kire mesh.obj --save out --wogui # save rendered images to the out folder (controlled by --elevation and --num_azimuth)
```

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

### Install kiui[kia] from PyPI

Source: https://kit.kiui.moe/_sources/agent.md.txt

Installs the agent and its optional dependencies from PyPI.

```bash
pip install "kiui[kia]"
```

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

### Slurm CLI usage examples

Source: https://kit.kiui.moe/slurm

A comprehensive set of command-line examples for the Slurm Utilities CLI (`ks`). It covers help, cluster info, job details, queue, history, log viewing, canceling jobs, pending jobs, and resource usage. The examples demonstrate various options and shortcuts.

```bash
python -m kiui.slurm --help
# short cut:
ks --help

# check cluster information (sinfo) — partitions, nodes, state with color
ks info
ks i # short cut

# check node details (scontrol show node) + running jobs on that node
ks i <nodename>

# check job details (scontrol show job / sacct fallback)
ks job <jobid>
ks j <jobid> # short cut
# also supports job name lookup (active jobs via squeue, then history via sacct)
ks j <jobname>

# show current user's jobs (squeue) with color-coded state, pending wait times
ks queue
ks q # short cut

# show all users' jobs
ks q -a

# show specific user's jobs
ks q -u <username>

# check job history (sacct), default last 3 days
ks history
ks h # short cut

# check job history for the last 7 days
ks h -d 7

# check job history for all users
ks h -a

# ── Log viewing ────────────────────────────────────────────────────

# Show per-rank training log (rank 0 by default, log_0.txt)
ks log <jobid>
ks l <jobid> # short cut

# Show a specific rank's log
ks l <jobid> -r 2

# Show the raw sbatch shell log (job.out)
ks l <jobid> -b

# Show the unified all-rank APS log
ks l <jobid> --aps

# With --batch, show stderr (job.err) instead
ks l <jobid> -b -e

# Show last 500 lines
ks l <jobid> -n 500

# Show all lines (no truncation)
ks l <jobid> -a

# Stream the log (tail -f)
ks l <jobid> -f

# Interactive: pick from your running jobs
ks l
ks l -u <username>

# ── Cancel jobs ────────────────────────────────────────────────────

# Interactive cancel (checkbox selection + confirmation)
ks cancel
ks c # short cut

# Direct cancel specific job(s) by ID
ks c <jobid>
ks c <jobid1> <jobid2>

# ── Pending jobs ───────────────────────────────────────────────────

# Show top 10 pending jobs sorted by priority (all users + your jobs)
ks pending
ks p # short cut

# Show top 20 pending jobs
ks p -n 20

# ── Resource usage ─────────────────────────────────────────────────

# Show cluster resource usage by user (sorted by GPU count)
ks usage
ks u # short cut

# Show top 10 users by resource usage
ks u -n 10

# Filter usage by partition
ks u -p batch
```

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

### Install latest development version from GitHub

Source: https://kit.kiui.moe/_sources/agent.md.txt

Installs the latest development version directly from the GitHub repository.

```bash
pip install -U "kiui[kia] @ git+https://github.com/ashawkey/kiuikit.git"
```

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

### Minimal SKILL.md example

Source: https://kit.kiui.moe/_sources/agent.md.txt

A minimal SKILL.md file with frontmatter (name and description) and instructions referencing a workflow and a script.

```markdown
---
name: pdf-processing
description: Extract, inspect, merge, and fill PDF documents. Use for PDF tasks.
---

Follow the workflow in `references/workflow.md`.
Use `scripts/extract.py` when text extraction is required.
```

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

### Install Kiuikit via pip

Source: https://kit.kiui.moe/_sources/index.md.txt

Install the minimal package with 'pip install kiui' or optional dependencies with 'pip install kiui[full]'. For the latest version, install directly from the GitHub repository.

```bash
# released
pip install kiui # install the minimal package
pip install kiui[full] # install optional dependencies

# latest
pip install -U git+https://github.com/ashawkey/kiuikit.git
```

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

### Start hub and launch agents

Source: https://kit.kiui.moe/_sources/agent.md.txt

Commands to start the hub once with --web-port 8765, then launch agents in other terminals that automatically discover and join the hub.

```bash
# terminal 1: owns the browser UI port
kia --hub --web-port 8765

# other terminals: automatically discover and join the hub
cd ~/project-a && kia --model gpt
cd ~/project-b && kia --model local
```

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

### Example video info output

Source: https://kit.kiui.moe/_sources/video.md.txt

Example output from the kivi info command for a video file.

```text
      Video Info: input.mp4      
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field       ┃ Value                                 ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Type        │ Video                                 │
│ Resolution  │ 640 x 480                             │
│ FPS         │ 30.000                                │
│ Duration    │ 00:00:05 (5.00 s)                     │
│ Frames      │ 150                                   │
│ Codec       │ h264 (encoders: libx264 / h264_nvenc) │
│ Codec tag   │ avc1                                  │
│ Bitrate     │ 1569577 bps                           │
│ File size   │ 957.99 KB                             │
│ Compression │ 140.92x (raw / encoded)               │
└─────────────┴───────────────────────────────────────┘
```

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

### Usage examples for miscellaneous CLI commands

Source: https://kit.kiui.moe/_sources/misc_cli.md.txt

Shows how to run each CLI utility with `python -m` or shortcut commands. Includes background removal, pose detection, captioning, edge detection, depth estimation, super-resolution, timer, mesh conversion, aesthetic prediction, directory comparison, and version locking. Note the extra dependency for depth_zoe and the shortcut commands `kisr` and `kico`.

```python
# background removal utils
python -m kiui.cli.bg --help
python -m kiui.cli.bg input.png output.png
python -m kiui.cli.bg input_folder output_folder

# openpose detector
python -m kiui.cli.pose --help

# blip2 image captioning
python -m kiui.cli.blip --help

# hed edge detector
python -m kiui.cli.hed --help

# zoe depth estimation (extra dep: pip install timm==0.6.11)
python -m kiui.cli.depth_zoe --help

# midas depth estimation (dpt-large)
python -m kiui.cli.depth_midas --help

# sr (Real-ESRGAN from https://github.com/ai-forever/Real-ESRGAN/tree/main)
python -m kiui.sr --help
python -m kiui.sr image.jpg --scale 2 # save to image_2x.jpg
kisr image.jpg --scale 2 # short cut cmd

# made-in-heaven timer (https://github.com/ashawkey/made-in-heaven-timer)
python -m kiui.cli.timer --help

# mesh format conversion (only for a single textured mesh in obj/glb)
python -m kiui.cli.convert input.obj output.glb
kico input.obj output.glb # short cut cmd
kico mesh_folder/ video_folder --fmt .mp4 # render all meshes into rotating videos

# aesthetic predictor v2 (https://github.com/christophschuhmann/improved-aesthetic-predictor)
python -m kiui.cli.aes --help

# compare content of two directories
python -m kiui.cli.dircmp <dir1> <dir2>

# lock requirements.txt package versions based on current environment
python -m kiui.cli.lock_version <requirements.txt>
```

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

### Render mesh with GUI and various options

Source: https://kit.kiui.moe/_sources/render.md.txt

Examples of opening a GUI to render a mesh, including options for CUDA rasterization fallback, resolution, anti-aliasing, front direction, and PBR rendering.

```bash
## open a GUI to render a mesh
kire mesh.obj
kire mesh.obj --force_cuda_rast # if you cannot use OpenGL backend (usually happens for headless servers), this will fallback to CUDA backend with some limitations (ref: https://nvlabs.github.io/nvdiffrast/#rasterizing-with-cuda-vs-opengl-new)
kire mesh.obj --H 800 --W 800 --ssaa 2 # set resolution and use super-sampling anti-aliasing

kire mesh.obj --front_dir +x # specify mesh front-facing dir, default is +z (OpenGL convention). You can use [+-][xyz] to specify axis, and [123] to specify clockwise rotation (per 90 degree).

kire mesh.glb --pbr # render with PBR (metallic + roughness)
kire mesh.glb --pbr --envmap env.hdr # specify hdr file
```

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

### Install kiuikit agent with optional dependencies

Source: https://kit.kiui.moe/agent

Install the agent and its optional dependencies from PyPI. Use the second command for the latest development version from GitHub.

```bash
pip install "kiui[kia]"

```

```bash
pip install -U "kiui[kia] @ git+https://github.com/ashawkey/kiuikit.git"

```

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

### Install bpy and mathutils

Source: https://kit.kiui.moe/_sources/blender.md.txt

Install the required Python packages for Blender rendering. Requires Python >= 3.10 and tested with bpy==4.0.0.

```bash
pip install bpy mathutils
```

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

### Slurm CLI help and shortcuts

Source: https://kit.kiui.moe/_sources/slurm.md.txt

Shows how to get help for the Slurm utilities and the shortcut command 'ks'.

```bash
python -m kiui.slurm --help
# short cut:
ks --help
```

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

### Configure .kiui.yaml with model profiles

Source: https://kit.kiui.moe/_sources/agent.md.txt

Example .kiui.yaml configuration defining OpenAI-compatible model profiles and an optional web token. Project configuration takes precedence over global.

```yaml
openai:
  gpt:                         # short alias used by kia
    model: gpt-5               # model ID sent to the provider
    api_key: sk-...
    base_url: https://api.openai.com/v1
    reasoning_effort: high     # optional

  local:
    model: my-model
    api_key: not-needed
    base_url: http://localhost:8000/v1

kia_web_token: change-me       # optional fixed Web UI token
```

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

### Render without GUI on headless servers

Source: https://kit.kiui.moe/_sources/render.md.txt

Examples of running the renderer without a GUI to save a rotating video or rendered images.

```bash
## we can also run without GUI on headless servers
kire mesh.obj --save_video out.mp4 --wogui # save 360 degree rotating video
kire mesh.obj --save out --wogui # save rendered images to the out folder (controlled by --elevation and --num_azimuth)
```

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

### Start kia with a model

Source: https://kit.kiui.moe/agent

Run kia from the root of the project you want it to work on. If --model is omitted, the first profile in openai is used.

```bash
cd my-project
kia --model gpt

```

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

### Blender rendering commands

Source: https://kit.kiui.moe/blender

Commands to install dependencies and run the Blender rendering script with various options.

```bash
# make sure you are using python>=3.10, tested with bpy==4.0.0
pip install bpy mathutils

# help
python -m kiui.cli.blender_render --help

# example
python -m kiui.cli.blender_render --mesh chest.glb --gpu 0 --depth --normal --pbr --camera --blend

# example with wireframe
python -m kiui.cli.blender_render --mesh chest.glb --wireframe

```

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

### Skill directory structure

Source: https://kit.kiui.moe/_sources/agent.md.txt

Example layout of a skill pack under .kia/skills/, showing optional scripts, references, and assets directories.

```text
.kia/skills/pdf-processing/
├── SKILL.md
├── scripts/       # optional
├── references/    # optional
└── assets/        # optional
```

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

### Run kia with a specific model

Source: https://kit.kiui.moe/_sources/agent.md.txt

Starts the agent from the project root, selecting the 'gpt' profile. If --model is omitted, the first profile in openai is used.

```bash
cd my-project
kia --model gpt
```

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

### Natural language prompts for kia

Source: https://kit.kiui.moe/_sources/agent.md.txt

Example natural-language prompts for the agent, including an @ path reference for autocompletion.

```text
> explain how authentication flows through this repository
> fix the parser bug reported in issue #42 and run its tests
> compare these two approaches using current upstream documentation
> @src/server.py simplify this function without changing its API
```

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

### kib skill management commands

Source: https://kit.kiui.moe/_sources/agent.md.txt

Commands to list, install, update, upload, and remove skills in the personal skill library.

```bash
kib list
kib list --local
kib install pdf-processing
kib update [pdf-processing ...]
kib update pdf-processing --prefer local
kib upload pdf-processing
kib upload pdf-processing --force
kib remove pdf-processing
kib remove pdf-processing --local
```

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

### Load camera parameters, aggregate points, and export colored PLY

Source: https://kit.kiui.moe/_sources/camera.md.txt

This example loads camera parameters from JSON files using `glob_sorted` and `load_data`, converts all camera poses to point clouds, concatenates all points and colors, scales colors to 0-255, and exports the result as a colored PLY file using `export_ply_with_color`. It is intended for checking the point cloud in tools like MeshLab.

```python
camera_paths = glob_sorted("camera_params/*.json")

all_c2ws = []
all_points = []
all_colors = []
for path in tqdm.tqdm(camera_paths):
    c2w, points, rgb = load_data(path, target_size=(320, 180))
    all_c2ws.append(c2w)
    all_points.append(points)
    all_colors.append(rgb)

# visualize the camera poses as point clouds
axis_points, axis_colors = c2w_to_pointcloud(all_c2ws, point_per_axis=5, axis_length=1.0)
all_points.append(axis_points)
all_colors.append(axis_colors)

# concatenate all the points and colors
all_points = np.concatenate(all_points, axis=0)
all_colors = np.concatenate(all_colors, axis=0)
all_colors = np.clip(all_colors * 255.0, 0.0, 255.0).astype(np.uint8)

# save colored point cloud (e.g., check with meshlab)
export_ply_with_color(all_points, all_colors, "world_pointcloud.ply")
```

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

### List and switch personas with slash commands

Source: https://kit.kiui.moe/_sources/agent.md.txt

Use `/persona` to list installed personas and their tool surface. Use `/persona chatter` to switch to another persona; this restarts the conversation, similar to `/clear`.

```text
/persona                list installed personas and their tool surface
/persona chatter        switch persona (restarts the conversation, like /clear)
```

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

### Start kiui agent with a specific persona using --persona flag

Source: https://kit.kiui.moe/_sources/agent.md.txt

Use this command to launch the agent with a non-default persona, such as `chatter`. The `chatter` persona is a general chatbot with only `web_search` and `web_fetch` tools, no file/shell access, and no environment context.

```bash
kia --persona chatter   # start as another persona
```

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

### Show CLI help via module

Source: https://kit.kiui.moe/_sources/video.md.txt

Run the video tools as a module to display help.

```bash
python -m kiui.video --help
```

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

### Show CLI help via kivi shortcut

Source: https://kit.kiui.moe/_sources/video.md.txt

Run the video tools using the kivi shortcut to display help.

```bash
kivi --help
```

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

### Create share-friendly preview with kivi preview

Source: https://kit.kiui.moe/video

Commands to create a preview under a target size, with options for output path, target MB, resolution cap, framerate cap, quality floor, and audio bitrate.

```bash
# Create a preview that stays under 10 MB (default)
kivi preview input.mp4

# Specify output path and target size
kivi preview input.mp4 output.mp4 --target-mb 20

# Cap resolution and framerate
kivi preview input.mp4 --max-resolution 1280 --max-fps 24

# Adjust quality floor
kivi preview input.mp4 --crf 18 --preset slow

# Drop audio
kivi preview input.mp4 --audio-kbps 0

```

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

### kiss --help

Source: https://kit.kiui.moe/_sources/sys.md.txt

Displays the help information for the `kiss` CLI.

```bash
# help
kiss --help
```

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

### Start kia with the chatter persona

Source: https://kit.kiui.moe/agent

Starts the kia agent with the chatter persona, which is a general chatbot limited to web_search and web_fetch, with no file/shell access and no environment context in its prompt.

```bash
kia --persona chatter   # start as another persona

```

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

### Run video tools via kivi shortcut

Source: https://kit.kiui.moe/video

Shows how to invoke the video tools using the `kivi` shortcut.

```bash
kivi --help

```

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

### Create preview with custom output and target size

Source: https://kit.kiui.moe/_sources/video.md.txt

Specifies output path and target maximum file size in MB.

```bash
# Specify output path and target size
kivi preview input.mp4 output.mp4 --target-mb 20
```

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

### kiss CLI: help and OS info

Source: https://kit.kiui.moe/sys

Shows the kiss CLI help and prints OS/system information. Use these commands to inspect the system via the kiss utility.

```bash
kiss --help
```

```bash
kiss os
```

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

### Command line utilities for background removal, pose detection, captioning, etc.

Source: https://kit.kiui.moe/misc_cli

Shows how to invoke various CLI utilities from the kiui package via `python -m` commands. Each command includes the appropriate module (`bg`, `pose`, `blip`, etc.) and common options like `--help`. For background removal, the command can accept an input image or a folder. Includes a note for `depth_zoe` that requires `timm==0.6.11` as an extra dependency.

```bash
# background removal utils
python -m kiui.cli.bg --help
python -m kiui.cli.bg input.png output.png
python -m kiui.cli.bg input_folder output_folder

# openpose detector
python -m kiui.cli.pose --help

# blip2 image captioning
python -m kiui.cli.blip --help

# hed edge detector
python -m kiui.cli.hed --help

# zoe depth estimation (extra dep: pip install timm==0.6.11)
python -m kiui.cli.depth_zoe --help

# midas depth estimation (dpt-large)
python -m kiui.cli.depth_midas --help

# sr (Real-ESRGAN from https://github.com/ai-forever/Real-ESRGAN/tree/main)
python -m kiui.sr --help
python -m kiui.sr image.jpg --scale 2 # save to image_2x.jpg
kisr image.jpg --scale 2 # short cut cmd

# made-in-heaven timer (https://github.com/ashawkey/made-in-heaven-timer)
python -m kiui.cli.timer --help

# mesh format conversion (only for a single textured mesh in obj/glb)
python -m kiui.cli.convert input.obj output.glb
kico input.obj output.glb # short cut cmd
kico mesh_folder/ video_folder --fmt .mp4 # render all meshes into rotating videos

# aesthetic predictor v2 (https://github.com/christophschuhmann/improved-aesthetic-predictor)
python -m kiui.cli.aes --help

# compare content of two directories
python -m kiui.cli.dircmp <dir1> <dir2>

# lock requirements.txt package versions based on current environment
python -m kiui.cli.lock_version <requirements.txt>

```

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

### Show help for blender_render

Source: https://kit.kiui.moe/_sources/blender.md.txt

Display the command-line help for the Blender rendering script.

```bash
python -m kiui.cli.blender_render --help
```

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

### Render with depth, normal, PBR, camera, and blend

Source: https://kit.kiui.moe/_sources/blender.md.txt

Render a mesh with depth, normal, PBR, camera, and blend options using GPU 0.

```bash
python -m kiui.cli.blender_render --mesh chest.glb --gpu 0 --depth --normal --pbr --camera --blend
```

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

### Run video module via Python

Source: https://kit.kiui.moe/video

Shows how to invoke the video tools using the module directly.

```bash
python -m kiui.video --help

```

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

### List configured profiles with kia --list

Source: https://kit.kiui.moe/_sources/agent.md.txt

Lists configured profiles and their detected capabilities.

```bash
kia --list
```

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

### Create preview under 10 MB

Source: https://kit.kiui.moe/_sources/video.md.txt

Creates a share-friendly preview that stays under the default 10 MB target.

```bash
# Create a preview that stays under 10 MB (default)
kivi preview input.mp4
```

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

### main() CLI for rendering pinhole images from equirectangular input

Source: https://kit.kiui.moe/_modules/kiui/equirect

Command-line entry point that reads an equirectangular image, optionally tonemaps HDR EXR inputs to LDR, and calls render_pinhole to produce pinhole images. Uses argparse with defaults for height/width (512), vfov (60.0), roll/pitch/yaw (0.0), and output directory './results'.

```python
def main():
    import argparse
    import kiui 
    import os

    parser = argparse.ArgumentParser()
    parser.add_argument('path', type=str, help="path to equirectangular image (exr, hdr, png, jpg, ...)")
    parser.add_argument('--height', type=int, default=512, help="image height")
    parser.add_argument('--width', type=int, default=512, help="image width")
    parser.add_argument('--vfov', type=float, default=60.0, help="vertical field of view in degrees")
    parser.add_argument('--roll', type=float, default=0.0, help="roll angle in degrees")
    parser.add_argument('--pitch', type=float, default=0.0, help="pitch angle in degrees")
    parser.add_argument('--yaw', type=float, default=0.0, help="yaw angle in degrees")
    parser.add_argument('--output', type=str, default='./results', help="output directory")
    args = parser.parse_args()

    equirect = kiui.read_image(args.path, mode="float", order="RGB")
    kiui.lo(equirect)
    
    if args.path.endswith('.exr'):
        equirect = tonemap_hdr_to_ldr(equirect)
        kiui.write_image(os.path.join(args.output, f'{os.path.basename(args.path).split(".")[0]}_ldr.jpg'), equirect)
        print("[INFO] tonemapped to LDR:")
        kiui.lo(equirect)
    
    equirect = torch.from_numpy(equirect).permute(2, 0, 1)  # [3, Hp, Wp]
    height = args.height
    width = args.width
    vfov = torch.tensor([np.deg2rad(args.vfov)])
    roll = torch.tensor([np.deg2rad(args.roll)])
    pitch = torch.tensor([np.deg2rad(args.pitch)])
    yaw = torch.tensor([np.deg2rad(args.yaw)])
    
    images = render_pinhole(equirect, height, width, vfov, roll, pitch, yaw)
    print("[INFO] rendered pinhole images:")
    kiui.lo(images)
```

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

### Invoke renderer with kire --help

Source: https://kit.kiui.moe/_sources/render.md.txt

Shows how to invoke the renderer's help. The first command is a short alias for the second.

```bash
# invoke renderer
kire --help 
# this is short for
python -m kiui.render --help
```

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

### Configure personal skill library

Source: https://kit.kiui.moe/_sources/agent.md.txt

YAML configuration setting kia_lib to a Git repository for sharing skills between projects.

```yaml
kia_lib: git@github.com:username/kia-skills.git
```

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

### Load, inspect, and write a mesh with kiui.mesh.Mesh

Source: https://kit.kiui.moe/_sources/mesh.md.txt

Shows how to load a mesh from a GLB file, inspect its attributes (vertices, faces, albedo, texture coordinates, normals), and write it to an OBJ file. Requires PyTorch and a CUDA-capable device if available.

```python
import kiui
from kiui.mesh import Mesh

# load mesh
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
mesh = Mesh.load('model.glb', device=device)

# inspect attributes
kiui.lo(mesh.v, mesh.f, mesh.albedo, mesh.vt, mesh.ft, mesh.vn, mesh.fn)

# write mesh (can change to obj format)
mesh.write('model.obj')
```

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

### Create preview with quality adjustments

Source: https://kit.kiui.moe/_sources/video.md.txt

Adjusts CRF quality ceiling and preset for the preview.

```bash
# Adjust quality floor
kivi preview input.mp4 --crf 18 --preset slow
```

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

### Complete script to verify camera and depth conventions and export point cloud

Source: https://kit.kiui.moe/_sources/camera.md.txt

Loads camera parameters (projection and view transform), depth (distance to camera center), and RGB image. Constructs world-space rays, normalizes them because depth is to camera center, and exports a colored PLY point cloud. Includes toggles for OpenGL camera convention (OPENGL_RAYS) and commented-out c2w flips. Requires kiui, cv2, numpy, plyfile, and tqdm.

```python
import os
import re
import cv2  
import kiui 
import glob
import tqdm
import numpy as np
from plyfile import PlyData, PlyElement

def glob_sorted(path: str):
    paths = glob.glob(path)
    def _natural_key(name: str):
        return [int(part) if part.isdigit() else part for part in re.split(r"(\d+)", name)]
    return sorted(
        paths,
        key=lambda p: _natural_key(os.path.splitext(os.path.basename(p))[0]),
    )

def export_ply_with_color(point_cloud: np.ndarray, colors: np.ndarray, file_path: str) -> None:
    assert point_cloud.shape[0] == colors.shape[0]
    vertices = np.zeros(
        point_cloud.shape[0],
        dtype=[("x", "f4"), ("y", "f4"), ("z", "f4"), ("red", "u1"), ("green", "u1"), ("blue", "u1")],
    )
    vertices["x"] = point_cloud[:, 0].astype(np.float32)
    vertices["y"] = point_cloud[:, 1].astype(np.float32)
    vertices["z"] = point_cloud[:, 2].astype(np.float32)
    vertices["red"] = colors[:, 0].astype(np.uint8)
    vertices["green"] = colors[:, 1].astype(np.uint8)
    vertices["blue"] = colors[:, 2].astype(np.uint8)
    el = PlyElement.describe(vertices, "vertex")
    os.makedirs(os.path.dirname(file_path) or ".", exist_ok=True)
    PlyData([el]).write(file_path)


def load_data(path: str, target_size: tuple[int, int] = (320, 180)):
    
    # load camera
    cam_params = kiui.read_json(path)
    width, height = int(cam_params['renderProductResolution'][0]), int(cam_params['renderProductResolution'][1])
    proj = np.array(cam_params["cameraProjection"]).reshape(4, 4).T # [4, 4], perspective projection (T is for col-major to row-major)
    w2c = np.array(cam_params["cameraViewTransform"]).reshape(4, 4).T # [4, 4], world2cam 

    # get intrinsics from projection matrix
    fx = proj[0, 0] * (width / 2.0)
    fy = proj[1, 1] * (height / 2.0)
    cx = (1.0 - proj[0, 2]) * (width / 2.0)
    cy = (1.0 - proj[1, 2]) * (height / 2.0)

    c2w = np.linalg.inv(w2c)

    # load depth
    path_depth = path.replace("camera_params", "distance_to_camera").replace(".json", ".exr")
    depth = kiui.read_image(path_depth, mode="float")
    depth = depth.astype(np.float32) # [H, W]

    # downsample depth and intrinsics for visualization
    d_width, d_height = int(target_size[0]), int(target_size[1])
    d_depth = cv2.resize(depth, (d_width, d_height), interpolation=cv2.INTER_NEAREST)
    scale_x = float(d_width) / float(width)
    scale_y = float(d_height) / float(height)
    d_fx = fx * scale_x
    d_fy = fy * scale_y
    d_cx = cx * scale_x
    d_cy = cy * scale_y

    # create world space point cloud

    ### IMPORTANT: toggle camera convention 
    # here the camera is OpenGL convention actually

    # either toggle the c2w convention
    # c2w[:, 1] *= -1
    # c2w[:, 2] *= -1

    # or toggle the rays construction (but don't do both!).
    OPENGL_RAYS = True

    x, y = np.meshgrid(np.arange(d_width), np.arange(d_height), indexing="xy")
    x = x.reshape(-1)
    y = y.reshape(-1)
    rays_d = np.stack([
        (x - d_cx + 0.5) / d_fx,
        (y - d_cy + 0.5) / d_fy * (-1.0 if OPENGL_RAYS else 1.0),
        np.ones_like(x) * (-1.0 if OPENGL_RAYS else 1.0),
    ], axis=-1) # [hw, 3]

    rays_d = rays_d @ c2w[:3, :3].T  # [hw, 3]
    rays_o = np.expand_dims(c2w[:3, 3], 0).repeat(rays_d.shape[0], 0)  # [hw, 3]

    # since depth is to camera center, we need to normalize the rays_d
    rays_d = rays_d / np.linalg.norm(rays_d, axis=-1, keepdims=True)
    rays_o = rays_o.reshape(d_height, d_width, 3)
    rays_d = rays_d.reshape(d_height, d_width, 3)

    valid_mask = np.isfinite(d_depth) & (d_depth > 0)
    points = rays_d[valid_mask] * d_depth[valid_mask][:, None] + rays_o[valid_mask] # [N, 3] in world space

    # load rgb for color visualization
    path_rgb = path.replace("camera_params", "ldr_color").replace(".json", ".png")
    rgb = kiui.read_image(path_rgb, mode="float") # [H, W, 3]
    d_rgb = cv2.resize(rgb, (d_width, d_height), interpolation=cv2.INTER_AREA)
    d_rgb = d_rgb[valid_mask]  # [N, 3]

    return c2w, points, d_rgb
```

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

### kiss os

Source: https://kit.kiui.moe/_sources/sys.md.txt

Prints OS/system information using the `kiss` CLI.

```bash
# print OS/system information
kiss os
```

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

### Load camera data and build point cloud with load_data

Source: https://kit.kiui.moe/camera

Loads camera parameters, depth, and RGB from a JSON camera file, then builds a world-space point cloud. Reads intrinsics from the projection matrix, downsamples depth and intrinsics to target_size, and uses OPENGL_RAYS to toggle ray construction (do not also flip c2w). Returns c2w, points, and downsampled RGB colors.

```python
def load_data(path: str, target_size: tuple[int, int] = (320, 180)):

    # load camera
    cam_params = kiui.read_json(path)
    width, height = int(cam_params['renderProductResolution'][0]), int(cam_params['renderProductResolution'][1])
    proj = np.array(cam_params["cameraProjection"]).reshape(4, 4).T # [4, 4], perspective projection (T is for col-major to row-major)
    w2c = np.array(cam_params["cameraViewTransform"]).reshape(4, 4).T # [4, 4], world2cam

    # get intrinsics from projection matrix
    fx = proj[0, 0] * (width / 2.0)
    fy = proj[1, 1] * (height / 2.0)
    cx = (1.0 - proj[0, 2]) * (width / 2.0)
    cy = (1.0 - proj[1, 2]) * (height / 2.0)

    c2w = np.linalg.inv(w2c)

    # load depth
    path_depth = path.replace("camera_params", "distance_to_camera").replace(".json", ".exr")
    depth = kiui.read_image(path_depth, mode="float")
    depth = depth.astype(np.float32) # [H, W]

    # downsample depth and intrinsics for visualization
    d_width, d_height = int(target_size[0]), int(target_size[1])
    d_depth = cv2.resize(depth, (d_width, d_height), interpolation=cv2.INTER_NEAREST)
    scale_x = float(d_width) / float(width)
    scale_y = float(d_height) / float(height)
    d_fx = fx * scale_x
    d_fy = fy * scale_y
    d_cx = cx * scale_x
    d_cy = cy * scale_y

    # create world space point cloud

    ### IMPORTANT: toggle camera convention
    # here the camera is OpenGL convention actually

    # either toggle the c2w convention
    # c2w[:, 1] *= -1
    # c2w[:, 2] *= -1

    # or toggle the rays construction (but don't do both!).
    OPENGL_RAYS = True

    x, y = np.meshgrid(np.arange(d_width), np.arange(d_height), indexing="xy")
    x = x.reshape(-1)
    y = y.reshape(-1)
    rays_d = np.stack([
        (x - d_cx + 0.5) / d_fx,
        (y - d_cy + 0.5) / d_fy * (-1.0 if OPENGL_RAYS else 1.0),
        np.ones_like(x) * (-1.0 if OPENGL_RAYS else 1.0),
    ], axis=-1) # [hw, 3]

    rays_d = rays_d @ c2w[:3, :3].T  # [hw, 3]
    rays_o = np.expand_dims(c2w[:3, 3], 0).repeat(rays_d.shape[0], 0)  # [hw, 3]

    # since depth is to camera center, we need to normalize the rays_d
    rays_d = rays_d / np.linalg.norm(rays_d, axis=-1, keepdims=True)
    rays_o = rays_o.reshape(d_height, d_width, 3)
    rays_d = rays_d.reshape(d_height, d_width, 3)

    valid_mask = np.isfinite(d_depth) & (d_depth > 0)
    points = rays_d[valid_mask] * d_depth[valid_mask][:, None] + rays_o[valid_mask] # [N, 3] in world space

    # load rgb for color visualization
    path_rgb = path.replace("camera_params", "ldr_color").replace(".json", ".png")
    rgb = kiui.read_image(path_rgb, mode="float") # [H, W, 3]
    d_rgb = cv2.resize(rgb, (d_width, d_height), interpolation=cv2.INTER_AREA)
    d_rgb = d_rgb[valid_mask]  # [N, 3]

    return c2w, points, d_rgb
```

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

### Show per-rank training log with ks log

Source: https://kit.kiui.moe/_sources/slurm.md.txt

Shows per-rank training log (rank 0 by default, log_0.txt). Shortcut: 'ks l'.

```bash
# Show per-rank training log (rank 0 by default, log_0.txt)
ks log <jobid>
ks l <jobid> # short cut
```

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

### Create preview with resolution and framerate caps

Source: https://kit.kiui.moe/_sources/video.md.txt

Caps the longest spatial side and framerate for the preview.

```bash
# Cap resolution and framerate
kivi preview input.mp4 --max-resolution 1280 --max-fps 24
```

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

### Check node details with ks i <nodename>

Source: https://kit.kiui.moe/_sources/slurm.md.txt

Shows node details via 'scontrol show node' and running jobs on that node.

```bash
# check node details (scontrol show node) + running jobs on that node
ks i <nodename>
```

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

### Show all users' jobs with ks q -a

Source: https://kit.kiui.moe/_sources/slurm.md.txt

Shows all users' jobs.

```bash
# show all users' jobs
ks q -a
```

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

### Create preview without audio

Source: https://kit.kiui.moe/_sources/video.md.txt

Drops audio from the preview by setting audio bitrate to 0.

```bash
# Drop audio
kivi preview input.mp4 --audio-kbps 0
```

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

### Terminal session with kia --model gpt

Source: https://kit.kiui.moe/_sources/agent.md.txt

Shows a sample terminal session with the `kia` agent. The user invokes `kia --model gpt` and gives a task; the agent's actions and confirmation are displayed as bullet points.

```text
$ kia --model gpt
> find the cause of this failing test, fix it, and run the smallest relevant check

● reads the repository and test output
● edits only the affected files
● runs the focused test
✓ explains what changed and what was verified
```

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

### Inspect video information

Source: https://kit.kiui.moe/_sources/video.md.txt

Prints a rich table with video details such as resolution, FPS, duration, frames, codec, bitrate, file size, and compression ratio.

```bash
kivi info input.mp4
```
Tokens:
Raw