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.

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

// Create the selection custom operation compute bundle
let my_selection_custom_op_bundle = ComputeBundleBuilder::new()
    .label("My Selection")
    .bind_group_layouts([
        &SelectionBundle::GAUSSIANS_BIND_GROUP_LAYOUT_DESCRIPTOR,
        &MY_CUSTOM_BIND_GROUP_LAYOUT_DESCRIPTOR, // Put your custom bind group layout here.
    ])
    .resolver({
        let mut resolver = wesl::PkgResolver::new();
        resolver.add_package(&core::shader::PACKAGE); // Required for using core buffer structs.
        resolver.add_package(&shader::PACKAGE); // Optionally add this for some utility functions.
        resolver
    })
    .main_shader("path::to::my::wesl::module".parse().unwrap())
    .entry_point("main")
    .wesl_compile_options(wesl::CompileOptions {
        features: G::wesl_features(), // Required for enabling the correct features for core structs.
        ..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 the Gaussians buffer, so remember to start from 1 for your bind groups
        [my_selection_custom_op_buffer.buffer().as_entire_binding()], // Your custom bind group resources
    )
    .unwrap()

// Create the selection expression
let selection_expr = gs::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
    gs::SelectionExpr::Buffer(my_existing_selection_buffer) // An existing selection buffer for example
);

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

// Evaluate the selection expression
selection_bundle.evaluate(
    &device,
    &mut encoder,
    &selection_expr,
    &dest_selection_buffer,
    &model_transform,
    &gaussian_transform,
    &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<'a>(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 143)

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::default());

    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_features: wgpu::Features::empty(),
            required_limits: adapter.limits(),
            memory_hints: wgpu::MemoryHints::default(),
            trace: wgpu::Trace::Off,
        })
        .await
        .expect("device");

    log::debug!("Creating gaussians");
    let f = std::fs::File::open(model_path).expect("ply file");
    let mut reader = std::io::BufReader::new(f);
    let gaussians = gs::core::Gaussians::read_ply(&mut reader).expect("gaussians");

    log::debug!("Creating gaussians buffer");
    let gaussians_buffer =
        gs::core::GaussiansBuffer::<GaussianPod>::new(&device, &gaussians.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()));

    #[allow(unused_must_use)]
    device.poll(wgpu::PollType::Wait);

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

    log::debug!("Filtering Gaussians");
    let selected_gaussians = gs::core::Gaussians {
        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.gaussians.iter())
            .filter(|(selected, _)| *selected)
            .map(|(_, g)| g.clone())
            .collect::<Vec<_>>(),
    };

    log::debug!("Writing modified Gaussians to output file");
    let output_file = std::fs::File::create(&args.output).expect("output file");
    let mut writer = std::io::BufWriter::new(output_file);
    selected_gaussians
        .write_ply(&mut writer)
        .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 193-201)

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::default());

    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_features: wgpu::Features::empty(),
            required_limits: adapter.limits(),
            memory_hints: wgpu::MemoryHints::default(),
            trace: wgpu::Trace::Off,
        })
        .await
        .expect("device");

    log::debug!("Creating gaussians");
    let f = std::fs::File::open(model_path).expect("ply file");
    let mut reader = std::io::BufReader::new(f);
    let gaussians = gs::core::Gaussians::read_ply(&mut reader).expect("gaussians");

    log::debug!("Creating gaussians buffer");
    let gaussians_buffer =
        gs::core::GaussiansBuffer::<GaussianPod>::new(&device, &gaussians.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()));

    #[allow(unused_must_use)]
    device.poll(wgpu::PollType::Wait);

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

    log::debug!("Filtering Gaussians");
    let selected_gaussians = gs::core::Gaussians {
        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.gaussians.iter())
            .filter(|(selected, _)| *selected)
            .map(|(_, g)| g.clone())
            .collect::<Vec<_>>(),
    };

    log::debug!("Writing modified Gaussians to output file");
    let output_file = std::fs::File::create(&args.output).expect("output file");
    let mut writer = std::io::BufWriter::new(output_file);
    selected_gaussians
        .write_ply(&mut writer)
        .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.