Struct SelectionBundle 

pub struct SelectionBundle<G: GaussianPod> {
    pub bundles: Vec<ComputeBundle<()>>,
    /* private fields */
}

A collection of specialized ComputeBundle for selection operations.

Custom Operations

All ComputeBundles supplied to this bundle as a SelectionExpr::Unary, SelectionExpr::Binary, or SelectionExpr::Selection custom operation must have the same bind group 0 as the SelectionBundle::GAUSSIANS_BIND_GROUP_LAYOUT_DESCRIPTOR. They must also not have the bind group itself, as it will be supplied automatically during evaluation.

Note that SelectionExpr::Unary will also get the source selection buffer, but it will be empty (all zeros), you should operate on the destination selection buffer only.

It is recommended to use ComputeBundleBuilder to create the custom operation bundles, and build them using ComputeBundleBuilder::build_without_bind_groups.

// Create an editor that holds the buffers for the Gaussians
let editor = Editor::new(
    &device,
    &vec![core::Gaussian {
        rot: Quat::IDENTITY,
        pos: Vec3::ZERO,
        color: U8Vec4::ZERO,
        sh: [Vec3::ZERO; 15],
        scale: Vec3::ONE,
    }],
);

// Create the selection custom operation compute bundle
let my_selection_custom_op_bundle = core::ComputeBundleBuilder::new()
    .label("My Selection")
    .bind_group_layouts([
        &SelectionBundle::<GaussianPod>::GAUSSIANS_BIND_GROUP_LAYOUT_DESCRIPTOR,
        &MY_CUSTOM_BIND_GROUP_LAYOUT_DESCRIPTOR,
    ])
    .resolver({
        let mut resolver =
            wesl::StandardResolver::new("path/to/my/folder/containing/wesl");
        // Required for using core buffer structs.
        resolver.add_package(&core::shader::PACKAGE);
        // Optionally add this for some utility functions.
        resolver.add_package(&shader::PACKAGE);
        resolver
    })
    .main_shader("package::my_wesl_filename".parse().unwrap())
    .entry_point("main")
    .wesl_compile_options(wesl::CompileOptions {
        // Required for enabling the correct features for core struct.
        features: GaussianPod::wesl_features(),
        ..Default::default()
    })
    .build_without_bind_groups(&device)
    .map_err(|e| log::error!("{e}"))
    .expect("my selection custom op bundle");

// Create the selection bundle
let selection_bundle =
    SelectionBundle::<GaussianPod>::new(&device, vec![my_selection_custom_op_bundle]);

// Create the bind group for your custom operation
let my_selection_custom_op_bind_group = selection_bundle.bundles[0]
    .create_bind_group(
        &device,
        1, // Index 0 is always the Gaussians buffer
        [my_buffer.buffer().as_entire_binding()],
    )
    .unwrap();

// Create the selection expression
let selection_expr = SelectionExpr::selection(
    0, // The bundle index for your custom operation in the selection bundle
    vec![my_selection_custom_op_bind_group],
)
.union(
    // Combine with other selection expressions using different functions
    // Here is an existing selection buffer for example
    SelectionExpr::Buffer(my_existing_selection_buffer),
);

// Create a selection buffer for the result
let dest_selection_buffer =
    SelectionBuffer::new(&device, editor.gaussians_buffer.len() as u32);


// Evaluate the selection expression
selection_bundle.evaluate(
    &device,
    &mut encoder,
    &selection_expr,
    &dest_selection_buffer,
    &editor.model_transform_buffer,
    &editor.gaussian_transform_buffer,
    &editor.gaussians_buffer,
);

Shader Format

You may copy and paste the following shader bindings for SelectionBundle::GAUSSIANS_BIND_GROUP_LAYOUT_DESCRIPTOR into your custom selection operation shader to ensure that the bindings are correct, then add your own bindings after that.

import wgpu_3dgs_core::{
    gaussian::Gaussian,
    gaussian_transform::GaussianTransform,
    model_transform::{model_to_world, ModelTransform},
};

@group(0) @binding(0)
var<uniform> op: u32;

@group(0) @binding(1)
var<storage, read> source: array<u32>;

@group(0) @binding(2)
var<storage, read_write> dest: array<atomic<u32>>;

@group(0) @binding(3)
var<uniform> model_transform: ModelTransform;

@group(0) @binding(4)
var<uniform> gaussian_transform: GaussianTransform;

@group(0) @binding(5)
var<storage, read> gaussians: array<Gaussian>;

// Your custom bindings here...

override workgroup_size: u32;

@compute @workgroup_size(workgroup_size)
fn main(@builtin(global_invocation_id) id: vec3<u32>) {
    let index = id.x;

    if index >= arrayLength(&gaussians) {
        return;
    }

    let gaussian = gaussians[index];

    let world_pos = model_to_world(model_transform, gaussian.position);

    // Your custom selection operation code here...

    let word_index = index / 32u;
    let bit_index = index % 32u;
    let bit_mask = 1u << bit_index;
    if /* Condition for selecting the Gaussian */ {
        atomicOr(&dest[word_index], bit_mask);
    } else {
        atomicAnd(&dest[word_index], ~bit_mask);
    }
}

Fields

bundles: Vec<ComputeBundle<()>>

The compute bundles for selection custom operations.

Implementations

impl<G: GaussianPod> SelectionBundle<G>

pub const GAUSSIANS_BIND_GROUP_LAYOUT_DESCRIPTOR: BindGroupLayoutDescriptor<'static>

The Gaussians bind group layout descriptors.

This bind group layout takes the following buffers:

• SelectionOpBuffer
• Source SelectionBuffer
• Destination SelectionBuffer
• ModelTransformBuffer
• GaussianTransformBuffer
• GaussiansBuffer

pub const SPHERE_BIND_GROUP_LAYOUT_DESCRIPTOR: BindGroupLayoutDescriptor<'static>

The sphere selection bind group layout descriptor.

This bind group layout takes the following buffers:

• InvTransformBuffer

pub const BOX_BIND_GROUP_LAYOUT_DESCRIPTOR: BindGroupLayoutDescriptor<'static>

The box selection bind group layout descriptor.

This bind group layout takes the following buffers:

• InvTransformBuffer

pub fn new(device: &Device, bundles: Vec<ComputeBundle<()>>) -> Self

Create a new selection bundle.

bundles are used for SelectionExpr::Unary, SelectionExpr::Binary, or SelectionExpr::Selection as custom operations, they must have the same bind group 0 as the SelectionBundle::GAUSSIANS_BIND_GROUP_LAYOUT_DESCRIPTOR, see documentation of SelectionBundle for more details.

Examples found in repository

examples/filter_selection.rs (line 155)

async fn main() {
    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();

    let args = Args::parse();
    let model_path = &args.model;
    let pos = Vec3::from_slice(&args.pos);
    let rot = Quat::from_slice(&args.rot);
    let scale = Vec3::from_slice(&args.scale);
    let shape = match args.shape {
        Shape::Sphere => gs::SelectionBundle::<GaussianPod>::create_sphere_bundle,
        Shape::Box => gs::SelectionBundle::<GaussianPod>::create_box_bundle,
    };
    let repeat = args.repeat;
    let offset = Vec3::from_slice(&args.offset);

    log::debug!("Creating wgpu instance");
    let instance =
        wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle_from_env());

    log::debug!("Requesting adapter");
    let adapter = instance
        .request_adapter(&wgpu::RequestAdapterOptions::default())
        .await
        .expect("adapter");

    log::debug!("Requesting device");
    let (device, queue) = adapter
        .request_device(&wgpu::DeviceDescriptor {
            label: Some("Device"),
            required_limits: adapter.limits(),
            ..Default::default()
        })
        .await
        .expect("device");

    log::debug!("Creating gaussians");
    let gaussians = [
        gs::core::GaussiansSource::Ply,
        gs::core::GaussiansSource::Spz,
    ]
    .into_iter()
    .find_map(|source| gs::core::Gaussians::read_from_file(model_path, source).ok())
    .expect("gaussians");

    log::debug!("Creating gaussians buffer");
    let gaussians_buffer = gs::core::GaussiansBuffer::<GaussianPod>::new(&device, &gaussians);

    log::debug!("Creating model transform buffer");
    let model_transform = gs::core::ModelTransformBuffer::new(&device);

    log::debug!("Creating Gaussian transform buffer");
    let gaussian_transform = gs::core::GaussianTransformBuffer::new(&device);

    log::debug!("Creating shape selection compute bundle");
    let shape_selection = shape(&device);

    log::debug!("Creating selection bundle");
    let selection_bundle = gs::SelectionBundle::<GaussianPod>::new(&device, vec![shape_selection]);

    log::debug!("Creating shape selection buffers");
    let shape_selection_buffers = (0..repeat)
        .map(|i| {
            let offset_pos = pos + offset * i as f32;
            let buffer = gs::InvTransformBuffer::new(&device);
            buffer.update_with_scale_rot_pos(&queue, scale, rot, offset_pos);
            buffer
        })
        .collect::<Vec<_>>();

    log::debug!("Creating shape selection bind groups");
    let shape_selection_bind_groups = shape_selection_buffers
        .iter()
        .map(|buffer| {
            selection_bundle.bundles[0]
                .create_bind_group(
                    &device,
                    // index 0 is the Gaussians buffer, so we use 1,
                    // see docs of create_sphere_bundle or create_box_bundle
                    1,
                    [buffer.buffer().as_entire_binding()],
                )
                .expect("bind group")
        })
        .collect::<Vec<_>>();

    log::debug!("Creating selection expression");
    let selection_expr = shape_selection_bind_groups.into_iter().fold(
        gs::SelectionExpr::Identity,
        |acc, bind_group| {
            acc.union(gs::SelectionExpr::selection(
                0, // the 0 here is the bundle index in the selection bundle
                vec![bind_group],
            ))
        },
    );

    log::debug!("Creating destination buffer");
    let dest = gs::SelectionBuffer::new(&device, gaussians_buffer.len() as u32);

    log::info!("Starting selection process");
    let time = std::time::Instant::now();

    log::debug!("Selecting Gaussians");
    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
        label: Some("Selection Encoder"),
    });

    selection_bundle.evaluate(
        &device,
        &mut encoder,
        &selection_expr,
        &dest,
        &model_transform,
        &gaussian_transform,
        &gaussians_buffer,
    );

    queue.submit(Some(encoder.finish()));

    device
        .poll(wgpu::PollType::wait_indefinitely())
        .expect("poll");

    log::info!("Editing process completed in {:?}", time.elapsed());

    log::debug!("Filtering Gaussians");
    let selected_gaussians = dest
        .download::<u32>(&device, &queue)
        .await
        .expect("selected download")
        .iter()
        .flat_map(|group| {
            std::iter::repeat_n(group, 32)
                .enumerate()
                .map(|(i, g)| g & (1 << i) != 0)
        })
        .zip(gaussians.iter_gaussian())
        .filter(|(selected, _)| *selected)
        .map(|(_, g)| g)
        .collect::<Vec<_>>();

    let selected_gaussians = match &args.output[args.output.len().saturating_sub(4)..] {
        ".ply" => gs::core::Gaussians::Ply(gs::core::PlyGaussians::from_iter(
            selected_gaussians.into_iter(),
        )),
        ".spz" => {
            gs::core::Gaussians::Spz(
                gs::core::SpzGaussians::from_gaussians_with_options(
                    selected_gaussians,
                    &gs::core::SpzGaussiansFromGaussianSliceOptions {
                        version: 2, // Version 2 is more widely supported as of now
                        ..Default::default()
                    },
                )
                .expect("SpzGaussians from gaussians"),
            )
        }
        _ => panic!("Unsupported output file extension, expected .ply or .spz"),
    };

    log::debug!("Writing modified Gaussians to output file");
    selected_gaussians
        .write_to_file(&args.output)
        .expect("write modified Gaussians to output file");

    log::info!("Filtered Gaussians written to {}", args.output);
}

pub fn gaussians_bind_group_layout(&self) -> &BindGroupLayout

Get the Gaussians bind group layout.

pub fn evaluate( &self, device: &Device, encoder: &mut CommandEncoder, expr: &SelectionExpr, dest: &SelectionBuffer, model_transform: &ModelTransformBuffer, gaussian_transform: &GaussianTransformBuffer, gaussians: &GaussiansBuffer<G>, )

Evaluate and apply the selection expression.

Examples found in repository

examples/filter_selection.rs (lines 205-213)

async fn main() {
    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();

    let args = Args::parse();
    let model_path = &args.model;
    let pos = Vec3::from_slice(&args.pos);
    let rot = Quat::from_slice(&args.rot);
    let scale = Vec3::from_slice(&args.scale);
    let shape = match args.shape {
        Shape::Sphere => gs::SelectionBundle::<GaussianPod>::create_sphere_bundle,
        Shape::Box => gs::SelectionBundle::<GaussianPod>::create_box_bundle,
    };
    let repeat = args.repeat;
    let offset = Vec3::from_slice(&args.offset);

    log::debug!("Creating wgpu instance");
    let instance =
        wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle_from_env());

    log::debug!("Requesting adapter");
    let adapter = instance
        .request_adapter(&wgpu::RequestAdapterOptions::default())
        .await
        .expect("adapter");

    log::debug!("Requesting device");
    let (device, queue) = adapter
        .request_device(&wgpu::DeviceDescriptor {
            label: Some("Device"),
            required_limits: adapter.limits(),
            ..Default::default()
        })
        .await
        .expect("device");

    log::debug!("Creating gaussians");
    let gaussians = [
        gs::core::GaussiansSource::Ply,
        gs::core::GaussiansSource::Spz,
    ]
    .into_iter()
    .find_map(|source| gs::core::Gaussians::read_from_file(model_path, source).ok())
    .expect("gaussians");

    log::debug!("Creating gaussians buffer");
    let gaussians_buffer = gs::core::GaussiansBuffer::<GaussianPod>::new(&device, &gaussians);

    log::debug!("Creating model transform buffer");
    let model_transform = gs::core::ModelTransformBuffer::new(&device);

    log::debug!("Creating Gaussian transform buffer");
    let gaussian_transform = gs::core::GaussianTransformBuffer::new(&device);

    log::debug!("Creating shape selection compute bundle");
    let shape_selection = shape(&device);

    log::debug!("Creating selection bundle");
    let selection_bundle = gs::SelectionBundle::<GaussianPod>::new(&device, vec![shape_selection]);

    log::debug!("Creating shape selection buffers");
    let shape_selection_buffers = (0..repeat)
        .map(|i| {
            let offset_pos = pos + offset * i as f32;
            let buffer = gs::InvTransformBuffer::new(&device);
            buffer.update_with_scale_rot_pos(&queue, scale, rot, offset_pos);
            buffer
        })
        .collect::<Vec<_>>();

    log::debug!("Creating shape selection bind groups");
    let shape_selection_bind_groups = shape_selection_buffers
        .iter()
        .map(|buffer| {
            selection_bundle.bundles[0]
                .create_bind_group(
                    &device,
                    // index 0 is the Gaussians buffer, so we use 1,
                    // see docs of create_sphere_bundle or create_box_bundle
                    1,
                    [buffer.buffer().as_entire_binding()],
                )
                .expect("bind group")
        })
        .collect::<Vec<_>>();

    log::debug!("Creating selection expression");
    let selection_expr = shape_selection_bind_groups.into_iter().fold(
        gs::SelectionExpr::Identity,
        |acc, bind_group| {
            acc.union(gs::SelectionExpr::selection(
                0, // the 0 here is the bundle index in the selection bundle
                vec![bind_group],
            ))
        },
    );

    log::debug!("Creating destination buffer");
    let dest = gs::SelectionBuffer::new(&device, gaussians_buffer.len() as u32);

    log::info!("Starting selection process");
    let time = std::time::Instant::now();

    log::debug!("Selecting Gaussians");
    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
        label: Some("Selection Encoder"),
    });

    selection_bundle.evaluate(
        &device,
        &mut encoder,
        &selection_expr,
        &dest,
        &model_transform,
        &gaussian_transform,
        &gaussians_buffer,
    );

    queue.submit(Some(encoder.finish()));

    device
        .poll(wgpu::PollType::wait_indefinitely())
        .expect("poll");

    log::info!("Editing process completed in {:?}", time.elapsed());

    log::debug!("Filtering Gaussians");
    let selected_gaussians = dest
        .download::<u32>(&device, &queue)
        .await
        .expect("selected download")
        .iter()
        .flat_map(|group| {
            std::iter::repeat_n(group, 32)
                .enumerate()
                .map(|(i, g)| g & (1 << i) != 0)
        })
        .zip(gaussians.iter_gaussian())
        .filter(|(selected, _)| *selected)
        .map(|(_, g)| g)
        .collect::<Vec<_>>();

    let selected_gaussians = match &args.output[args.output.len().saturating_sub(4)..] {
        ".ply" => gs::core::Gaussians::Ply(gs::core::PlyGaussians::from_iter(
            selected_gaussians.into_iter(),
        )),
        ".spz" => {
            gs::core::Gaussians::Spz(
                gs::core::SpzGaussians::from_gaussians_with_options(
                    selected_gaussians,
                    &gs::core::SpzGaussiansFromGaussianSliceOptions {
                        version: 2, // Version 2 is more widely supported as of now
                        ..Default::default()
                    },
                )
                .expect("SpzGaussians from gaussians"),
            )
        }
        _ => panic!("Unsupported output file extension, expected .ply or .spz"),
    };

    log::debug!("Writing modified Gaussians to output file");
    selected_gaussians
        .write_to_file(&args.output)
        .expect("write modified Gaussians to output file");

    log::info!("Filtered Gaussians written to {}", args.output);
}

pub fn create_primitive_bundle(device: &Device) -> ComputeBundle<()>

Create the selection primitive operation ComputeBundle.

• Bind group 0 is SelectionBundle::GAUSSIANS_BIND_GROUP_LAYOUT_DESCRIPTOR.

You usually do not need to use this method, it is used internally for creating the primitive operation bundle for evaluation.

pub fn create_sphere_bundle(device: &Device) -> ComputeBundle<()>

Create a sphere selection custom operation.

• Bind group 0 is SelectionBundle::GAUSSIANS_BIND_GROUP_LAYOUT_DESCRIPTOR.
• Bind group 1 is SelectionBundle::SPHERE_BIND_GROUP_LAYOUT_DESCRIPTOR.

pub fn create_box_bundle(device: &Device) -> ComputeBundle<()>

Create a box selection custom operation.

• Bind group 0 is SelectionBundle::GAUSSIANS_BIND_GROUP_LAYOUT_DESCRIPTOR.
• Bind group 1 is SelectionBundle::BOX_BIND_GROUP_LAYOUT_DESCRIPTOR.

Trait Implementations

impl<G: Debug + GaussianPod> Debug for SelectionBundle<G>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.