Skip to content

Add getBinning/setBinning methods to MMCore #811

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marktsuchida merged 12 commits into from
Jan 29, 2026
Merged

Add getBinning/setBinning methods to MMCore #811

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
6f30d60
Add getBinning/setBinning methods to MMCore
nicost Jan 8, 2026
58d3e9c
MMCore: Make GetBinning use the camera Binning property.
nicost Jan 8, 2026
7a5748b
MMCore: Improved format detecting code in the setBinning function.
nicost Jan 8, 2026
e37129f
MMCore: get and setBinning enforce that binning format nxm
nicost Jan 16, 2026
64ee449
MMCore: Set and GetBinning, address Mark's comments.
nicost Jan 21, 2026
94ea852
DahengGalaxy: Fixed binning property, so that it will
nicost Jan 22, 2026
c7c220e
Core: Simplify Get and SetBinning.
nicost Jan 22, 2026
ffcebdb
Core: Add functiosn to detect binning values. Also addresses nipick …
nicost Jan 24, 2026
3606c2e
Core: changed type of binning functions to long.
nicost Jan 26, 2026
49b06ad
Clean up binning error handling
marktsuchida Jan 29, 2026
41f6d87
Match MMCoreJ POM version to MMCore version
marktsuchida Jan 29, 2026
66d6d3e
Merge branch 'main' into binning
marktsuchida Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 182 additions & 1 deletion MMCore/MMCore.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ namespace mmi = mmcore::internal;
* (Keep the 3 numbers on one line to make it easier to look at diffs when
* merging/rebasing.)
*/
const int MMCore_versionMajor = 11, MMCore_versionMinor = 11, MMCore_versionPatch = 0;
const int MMCore_versionMajor = 11, MMCore_versionMinor = 12, MMCore_versionPatch = 0;


///////////////////////////////////////////////////////////////////////////////
Expand Down Expand Up @@ -4407,6 +4407,187 @@ double CMMCore::getExposure(const char* label) MMCORE_LEGACY_THROW(CMMError)
return 0.0;
}

/**
* Returns the current binning setting of the camera.
* Binning values in "NxN" format (e.g., "2x2") are parsed to return the integer factor (e.g., 2).
* @return the binning factor (1-100)
*/
int CMMCore::getBinning() MMCORE_LEGACY_THROW(CMMError)
{
std::shared_ptr<mmi::CameraInstance> camera = currentCameraDevice_.lock();
if (!camera)
{
throw CMMError(getCoreErrorText(MMERR_CameraNotAvailable).c_str(), MMERR_CameraNotAvailable);
}
else
{
std::string cameraName;
{
mmi::DeviceModuleLockGuard guard(camera);
cameraName = camera->GetLabel();
}
return getBinning(cameraName.c_str());
}
}

/**
* Returns the current binning setting of the specified camera.
* Binning values in "NxN" format (e.g., "2x2") are parsed to return the integer factor (e.g., 2).
* @param label the camera device label
* @return the binning factor (1-100)
*/
int CMMCore::getBinning(const char* label) MMCORE_LEGACY_THROW(CMMError)
{
std::shared_ptr<mmi::CameraInstance> pCamera =
deviceManager_->GetDeviceOfType<mmi::CameraInstance>(label);

mmi::DeviceModuleLockGuard guard(pCamera);

if (!pCamera->HasProperty(MM::g_Keyword_Binning))
{
throw CMMError("Camera does not support binning property");
}

std::string binningValue = pCamera->GetProperty(MM::g_Keyword_Binning);

// Parse the binning value - handle both integer ("2") and NxN ("2x2") formats
if (binningValue.empty())
{
throw CMMError("Binning property returned empty value");
}

// atoi() naturally handles both formats - it parses until it hits non-digit
// "2" -> 2, "2x2" -> 2, "4x4" -> 4
int binning = atoi(binningValue.c_str());
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using atoi() for parsing is unsafe as it returns 0 for invalid input and doesn't provide error detection. For example, if the binning property returns "0", "abc", or other invalid values, atoi() will return 0, which will then fail the range check. However, if it returns something like "0x2", atoi() will parse it as 0, potentially missing a valid "2" value. Consider using std::stoi() with exception handling or checking if the first character is a digit before calling atoi() to ensure robust parsing.

Suggested change
// atoi() naturally handles both formats - it parses until it hits non-digit
// "2" -> 2, "2x2" -> 2, "4x4" -> 4
int binning = atoi(binningValue.c_str());
// Use std::stoi to parse leading digits and detect invalid formats
// "2" -> 2, "2x2" -> 2, "4x4" -> 4
int binning = 0;
try
{
std::size_t parsedChars = 0;
binning = std::stoi(binningValue, &parsedChars, 10);
if (parsedChars == 0)
{
throw CMMError("Invalid binning value (no leading digits): " + binningValue);
}
}
catch (const std::exception&)
{
throw CMMError("Invalid binning value: " + binningValue);
}

Copilot uses AI. Check for mistakes.

if (binning < 1 || binning > 100)
{
throw CMMError("Binning value out of valid range (1-100): " + binningValue);
}

return binning;
}

/**
* Sets the binning setting of the camera.
* Automatically handles both integer ("2") and "NxN" ("2x2") property formats.
* @param binning the binning factor (1-100)
*/
void CMMCore::setBinning(int binning) MMCORE_LEGACY_THROW(CMMError)
{
if (binning < 1 || binning > 100)
{
throw CMMError("Binning must be between 1 and 100");
}

std::shared_ptr<mmi::CameraInstance> camera = currentCameraDevice_.lock();
if (!camera)
{
throw CMMError(getCoreErrorText(MMERR_CameraNotAvailable).c_str(), MMERR_CameraNotAvailable);
}
else
{
std::string cameraName;
{
mmi::DeviceModuleLockGuard guard(camera);
cameraName = camera->GetLabel();
}
setBinning(cameraName.c_str(), binning);
}
}

/**
* Sets the binning setting of the specified camera.
* Automatically handles both integer ("2") and "NxN" ("2x2") property formats.
* @param label the camera device label
* @param binning the binning factor (1-100)
*/
void CMMCore::setBinning(const char* label, int binning) MMCORE_LEGACY_THROW(CMMError)
{
if (binning < 1 || binning > 100)
{
throw CMMError("Binning must be between 1 and 100");
}

std::shared_ptr<mmi::CameraInstance> pCamera =
deviceManager_->GetDeviceOfType<mmi::CameraInstance>(label);

{
mmi::DeviceModuleLockGuard guard(pCamera);
LOG_DEBUG(coreLogger_) << "Will set camera " << label <<
" binning to " << binning;

if (!pCamera->HasProperty(MM::g_Keyword_Binning))
{
throw CMMError("Camera does not support binning property");
}

// Try to determine the format by checking the current property value
std::string currentValue;
bool useNxNFormat = false;

try
{
currentValue = pCamera->GetProperty(MM::g_Keyword_Binning);
// If current value contains 'x' and looks like NxN format, use that
if (!currentValue.empty() && currentValue.find('x') != std::string::npos)
{
useNxNFormat = true;
}
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The format detection logic only checks for the presence of 'x' in the current value. This could incorrectly detect formats if the camera returns values like "max", "mixed", or other strings containing 'x'. Consider using a more robust check, such as a regex pattern to match "NxN" format (e.g., checking for digits before and after 'x'), or checking for a pattern like std::isdigit() before 'x' and after 'x'.

Copilot uses AI. Check for mistakes.
}
catch (...)
{
// If we can't get current value, we'll try integer format first
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The catch block catches all exceptions (catch (...)) but provides no logging or indication of what went wrong. This makes debugging difficult if GetProperty fails. Consider either catching specific exceptions and logging them at DEBUG level, or at minimum adding a debug log message indicating that the current value couldn't be retrieved and the default format will be tried.

Suggested change
// If we can't get current value, we'll try integer format first
// If we can't get current value, we'll try integer format first
LOG_DEBUG(coreLogger_) << "Could not retrieve current binning value for camera "
<< label << "; will try integer format first.";

Copilot uses AI. Check for mistakes.
}

// Build the property value string
std::string binningValue;
if (useNxNFormat)
{
// NxN format: "2x2", "4x4", etc.
std::string binStr = CDeviceUtils::ConvertToString(binning);
binningValue = binStr + "x" + binStr;
}
else
{
// Integer format: "2", "4", etc.
binningValue = CDeviceUtils::ConvertToString(binning);
}

// Try to set the property with detected format
try
{
pCamera->SetProperty(MM::g_Keyword_Binning, binningValue);
}
catch (const CMMError&)
{
// If it failed and we haven't tried the other format yet, try it
if (useNxNFormat)
{
// Tried NxN, now try integer
binningValue = CDeviceUtils::ConvertToString(binning);
}
else
{
// Tried integer, now try NxN
std::string binStr = CDeviceUtils::ConvertToString(binning);
binningValue = binStr + "x" + binStr;
}

// Try with alternate format (this will throw if it still fails)
pCamera->SetProperty(MM::g_Keyword_Binning, binningValue);
}

{
MMThreadGuard scg(stateCacheLock_);
stateCache_.addSetting(PropertySetting(label, MM::g_Keyword_Binning, binningValue.c_str()));
}
}

LOG_DEBUG(coreLogger_) << "Did set camera " << label <<
" binning to " << binning;
}
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new getBinning and setBinning methods lack test coverage. Given that the codebase includes unit tests (e.g., PixelSize-Tests.cpp tests binning-related functionality), these new API methods should have corresponding tests to verify:

  1. Parsing of integer format ("2")
  2. Parsing of NxN format ("2x2")
  3. Setting binning in both formats
  4. Error handling for cameras without binning support
  5. Error handling for invalid binning values
  6. The fallback mechanism when one format fails

Copilot uses AI. Check for mistakes.

/**
* Set the hardware region of interest for the current camera.
*
Expand Down
5 changes: 5 additions & 0 deletions MMCore/MMCore.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -394,6 +394,11 @@ class CMMCore
double getExposure() MMCORE_LEGACY_THROW(CMMError);
double getExposure(const char* label) MMCORE_LEGACY_THROW(CMMError);

int getBinning() MMCORE_LEGACY_THROW(CMMError);
int getBinning(const char* label) MMCORE_LEGACY_THROW(CMMError);
void setBinning(int binning) MMCORE_LEGACY_THROW(CMMError);
void setBinning(const char* label, int binning) MMCORE_LEGACY_THROW(CMMError);

void snapImage() MMCORE_LEGACY_THROW(CMMError);
void* getImage() MMCORE_LEGACY_THROW(CMMError);
void* getImage(unsigned numChannel) MMCORE_LEGACY_THROW(CMMError);
Expand Down